Webhooks allow you to build or set up integrations that subscribe to events in Oktopost. By subscribing to a webhook, Oktopost will send data to your custom URL every time an event happens.
Create a Webhook
To create a webhook go to Account Settings → Webhooks and click on New Webhook. Each webhook has the following properties:
|Name||The webhook name|
|Description||The webhook description|
|Event||The Oktopost event that will trigger this webhook|
|URL||The URL you use to submit data to|
|Secret||An auto-generated field, used for validating requests|
Note that Oktopost sends ALL webhook events using HTTP POST.
Oktopost supports the following events:
- A new note is added to a conversation
- A new conversation is available in your inbox
- A new comment or reply are available on existing conversation
- A conversation is assigned to a new user
- A conversation status is updated
People Database Events
- A social conversion is captured
- A new lead is captured
- A new social activity is detected
- A new message is added to the board
- A new topic is added to the board
- A new campaign is created
- A post is sent to social media
- A new post is created
- A scheduled post is updated
- A scheduled post is deleted
Approval Workflow Events
- A post or message is sent to the approval workflow
- A post or message is approved
- A post or message is rejected
The data sent with each event includes an array of JSON objects. For example, A new message is added to the board will include the message and the boards' metadata. With that, you may want to use the REST API to retrieve additional information about related 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 an 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.