Webhooks

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:

Property Description
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.

Supported Events

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.

Secure Connection

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.

Handling Responses

Response Headers

Each response will contain the following HTTP headers.

Header Description
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

Successful Responses

For each successful response your endpoint should return a 2xx HTTP response code.

Failed Responses

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.

Request Log

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.

Feedback and Knowledge Base