What is a Webhook?
A webhook is a process that delivers data in real time. They are typically event driven. A modern day example would be push notifications; when a certain event takes place, subscribers are immediately alerted that the event has taken place. Webhooks are useful because it reduces the need for API’s and will simply return data only when it is available and needed.
PlanOmatic Webhooks
Subscribers can use webhooks to receive notifications about particular events related to a PlanOmatic order. After subscribing to a webhook, simply wait for the webhook payload request and then execute code immediately after specific events occur on PlanOmatic orders. This is a more efficient alternative to making API calls periodically to check PlanOmatic data or order status. For example, many PlanOmatic customers ping the status of their order via the Order API V2 to determine if photo assets are available via the Data Feed API. However, if this process is updated to wait for a specific webhook whose data payload reveals what the status of an order is, then all subscribers need to do is wait to receive that particular status before requesting the Data Feed API. Webhooks render constant API requesting obsolete, and ensure quick and efficient data and photo exchange.
Anatomy of a Webhook
After configuring a webhook subscription, subscribed events will trigger a webhook notification each time they occur. This notification contains a JSON payload. A webhook subscription configuration will require the following data:
WEBHOOK - The webhook you are subscribing to. (i.e. ‘Order Status’)
CALLBACK URL - The callback URL that will receive the JSON payloads (i.e. ‘https://...’)
SUCCESS CODE - In order for the webhook job to know it was successful, your API will need to return an HTTP status code in the 200’s.
NOTIFICATION EMAIL - The email address to receive notices when webhook processes fail.
NOTE: We support API key parameters for our requests to the callback URL. Advanced authentication like header keys and OAuth are not currently supported. Webhook subscriptions are scoped only to the company that a subscriber is a part of. This means that when a webhook subscription is registered to PlanOmatic company, other companies can’t receive data payloads specific to your company.
Webhooks Usage
Its really simple! First, subscribe to the desired webhook (webhook list available below) via the subscriber object detailed above. Then, prepare a CALLBACK URL(ex: https://...) to expect an HTTPS POST request, where the payload will be sent via the request body. Our webhook process will attempt this request up to 10 times in one hour (every six minutes). If it fails all 10 times, the webhook will not be sent again so prepare your software for the payload! A failure is indicated by not receiving a 200-level status code from the callback url. If your API returns a 200, or 201 then that tells PlanOmatic that the subscriber received the payload and the webhook was successful. If the webhook process receives a 301, a status in the 400's, etc then the webhook will retry until it attempts 10 requests or receives a 200-level response code.