Webhooks allow you to build or set up integrations that subscribe to events in Oktopost. Webhooks will push data every time a certain event happens to a custom URL. For detailed instructions on how to use webhooks, please read the following article.
Create a Webhook
To create a webhook simply head over to Account Settings → Webhooks and click on New Webhook. Each webhook has the following properties:
|Name||The webhook name|
|Description||A short description of the webhooks' function|
|Event||The Oktopost event that will trigger this webhook|
|URL||The URL you use to submit data to|
|Secret||Auto-generated. Used for validating requests|
Once set up, Oktopost will send data to your URL via HTTP POST request every time an event happens.
Oktopost currently supports the following events:
- New conversion
- New assignment
- New note on existing assignment
- Assignment status changes
- New message is added to the board
The data sent for each events will include an array of JSON formatted objects that describe the related event. For example: New message on the board will include the message and the boards' meta data. With that, you may need to use the REST API to retrieve additional information about Oktopost objects.
To secure your endpoint you may wish to validate that it's actually receiving data from Oktopost and not from other, potentially malicious, sources.
To validate the request simply generate a HMACSHA1 hash from the Secret field and the raw payload (JSON string) received from the webhook (secret + payload) and compare it with the X-Oktopost-Secret HTTP header.
Each response will contain the following HTTP headers.
|X-Oktopost-Secret||Secret to compare the payload with|
|X-Oktopost-Webhook||The webhook Id|
|X-Oktopost-Payload||A list of comma separated payload Ids|
For each successful response your endpoint should return a 2xx HTTP response code.
If your endpoint fails to process the data it should respond with a 4xx or 5xx HTTP response code. In this case, Oktopost will attempt to resend the data in 10 minute intervals for up to 5 additional attempts.
If the issue will take longer to fix, you can deactivate the webhook and Oktopost will resend the data when the webhook is reactivated.
To examine which requests were sent to your endpoint, you can view the request log by clicking on the date under the Last Run column in the webhooks table. If no value is available it means that Oktopost never sent data to your endpoint.