Use the API to create a webhook

A webhook can be created through the interface or via the API. In this article, we will explain how you can setup a webhook via the API and which elements you should take into account when using the webhook.

To create a webhook via the API, a POST request must be made to:

POST ​/api​/v2​/webhooks

The attributes for creating webhooks are listed in the schema section of the webhook documentation. Additional information about setting up the webhook through the Ans API can be found in the top section of the API documentation under “Webhooks”.

Security

The webhooks API returns a secret after creating a new webhook. This secret can be used to verify that the webhook call comes from Ans by creating a SHA256 HMAC with the request body and this secret and comparing it to the X-Ans-Signature Header.

Retries

Webhook requests are automatically retried up to five times if the endpoint returns a response code other than 2xx. The request will also be retried if the request returned an SSL error or resulted in a Timeout. In case of a connection error, we assume the endpoint is no longer active and the webhook endpoint will be disabled. With the endpoint disabled, we will no longer send events to that webhook endpoint. You can always reenable the endpoint via the API or through the interface if the endpoint needs to become active again.

The time interval between retries is gradually extended by multiplying the retry count with a random jitter (between 30 seconds and 10 minutes). 

Events

Every webhook event is logged and contains the response code, headers and body of the response for debugging purposes. When an event failed to deliver and is being retried, we only store the response of the latest retry.

A list of webhook events for a particular webhook can be retrieved by performing a GET request to:

GET /api/v2/webhooks/{webhook_id}/events

The response will return a list of events that occurred on the specified webhook, along with the object to which the webhook is tied, a list of changes and a list of response codes.