Skip to main content

Managing webhooks

To automatically receive updates on a profile as soon as they occur, you must create a webhook. Each webhook event contains the profile information and the event details in the payload. If an event is enabled, the webhook will be triggered for all profiles in the system when it occurs.

You can register multiple webhook endpoints and enable as many events as you wish for each endpoint.

When an endpoint is registered for webhook, a secret token is generated for you to validate messages coming from the Amani system. This secret token will be passed as an HMAC signature in request headers.

Headers​

The following headers are included in every webhook request:

  • Content-Type: Set to application/json to indicate the payload format.
  • Content-Length: Specifies the size of the request body in bytes.
  • Webhook-Signature: A signature for verifying the webhook’s authenticity.

When configuring a webhook, you can specify custom headers as key-value pairs. These headers will be also included in the request sent to the webhook's target URL.

1. Get the list of events​

You can get the list of all available events and example payloads in the Amani system.

To enable/disable the events you must send {"enabled_events": ["event_name", ]} during webhook endpoint create/update.

curl '<base_url>/api/v2/events' \
-H 'Authorization: Bearer <user_token>' \

2. Create a webhook endpoint​

You should send the following informations during endpoint creation:

  1. Webhook URL
  2. Events your system needs to be notified for
  3. Custom headers you would like to receive for your webhooks
  4. Any metadata for your endpoint
curl --request POST '<base_url>/api/v2/webhook_endpoint' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <user_token>' \
--data '{
    "url": "webhook_url",
    "enabled_events": [],
    "custom_headers": {},
    "metadata": {}
}'

3. Get the secret token for your endpoint​

The secret token must be stored securely on your system.

curl '<base_url>/api/v2/webhook_endpoint/<endpoint_id>/secret' \
-H 'Authorization: Bearer <user_token>'

4. Generate a new secret token for your endpoint​

curl --request PATCH '<base_url>/api/v2/webhook_endpoint/<endpoint_id>/secret' \
-H 'Authorization: Bearer <user_token>' \

5. Update webhook​

You can update any information regarding your endpoint.

curl --request PUT '<base_url>/api/v2/webhook_endpoint/<endpoint_id>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <user_token>' \
--data '{
    "url": "webhook_url",
    "enabled_events": [],
    "custom_headers": {},
    "metadata": {}
}'

6. Get the logs for all triggered events for your endpoint​

You can get detailed logs for all events:

curl '<base_url>/api/v2/webhook_endpoint/{{endpoint_id}}/logs \
-H 'Authorization: Bearer <user_token>'

7. Retry a failed event​

You also have the option to retry triggering any failed event with the same payload.

curl --request POST '<base_url>/api/v2/webhook_endpoint/retry' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <user_token>' \
--data '{
    "log_id": "log_id"
}'

8. Test an event​

After registering your endpoint, you can test any of the events using dummy data:

curl --request POST '<base_url>/api/v2/webhook_endpoint/{{endpoint_id}}/test?event=event_name' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <user_token>'