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. (More information on events and payloads). If an event is enabled, the webhook will be triggered for all profiles in the system when it occurs.

When a webhook is created, 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 or as a webhook token in request headers depending on your preferences. During create you must specify this preference by setting {"signature_enabled": true/false} in request data (Read more on signature and webhook security).

1. Get the list of events​

You can get the list of all available events on the Amani system.

To enable/disable the events you must send {"event_name": true/false} during webhook create/update.

⚠️ All events are disabled by default unless specified.

Request:

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

Example response:

[
  "profile_create",
  "profile_update",
  "profile_status_change",
  "document_upload",
  "document_delete",
  "document_update",
  "document_status_change",
  "zip_file_create",
  "video_call_status_change",
  "profile_level_update"
]

2. Create webhook​

You should send the following informations during webhook creation:

  1. Webhook URL
  2. The security method (Signature Enabled/Disabled) (Read more on signature and webhook security.)
  3. Events your system needs to be notified for
curl --request PUT '<base_url>/api/v2/webhook' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <user_token>' \
--data '{
    "url": "webhook_url",
    "signature_enabled": true/false, //specify the security method
    "profile_create": true/false,
    "profile_update": true/false,
    "profile_status_change": true/false,
    "profile_level_update": true/false,
    "document_upload": true/false,
    "document_delete": true/false,
    "document_update": true/false,
    "document_status_change": true/false,
    "zip_file_create": true/false,
    "video_call_status_change": true/false,
}'

Response will include the url, events and their current statuses.

Status code: 200

{
  "id": "webhook uuid",
  "url": "webhook_url",
  "profile_create": false,
  "profile_update": false,
  "profile_status_change": false,
  "profile_level_update": false,
  "document_upload": false,
  "document_delete": false,
  "document_update": false,
  "document_status_change": false,
  "zip_file_create": false,
  "video_call_status_change": false,
  "signature_enabled": false
}

3. Get the secret token​

The secret token must be stored securely on your system.

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

Response:

Status code: 200

{
  "token": "<secret_token>"
}

4. Generate a new secret token​

curl --request PATCH '<base_url>/api/v2/webhook/token' \
-H 'Authorization: Bearer <user_token>' \

Response:

Status code: 200

{
  "token": "<secret_token>"
}

5. Update webhook​

You can update your webhook URL and security method and activate/deactivate the events.

curl --request PUT '<base_url>/api/v2/webhook' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <user_token>' \
--data '{
    "url": "webhook_url",
    "signature_enabled": true/false, //specify the security method
    "event_name": true/false
}'