Configuring Webhooks

The Webhook Management APIs allow users to:

Create a new webhook
Retrieve available webhook events
List all configured webhooks
Retrieve a single webhook

👍
Note
Webhooks can also configured on the lync dashboard.

1. Retrieve Available Webhook Events

This endpoint retrieves a list of all available webhook events that can be subscribed to.

To begin the webhook integration process, you need to retrieve the list of available events by sending a request to the endpoint below

Example Request

curl --location '<https://api.sandbox.waza.co/lync/v1/webhooks>' \\
--header 'x-waza-key: YOUR_WAZA_KEY'

Example Response

{
  "data": [
    "banking.transfer.created",
    "banking.transfer.completed"
  ]
}

Response Fields

Field	Type	Description
`data`	array	A list of available webhook events.
`data[]`	string	The name of the event that can be subscribed to (e.g., `"banking.payment.created"`).

2. Create a New Webhook

This endpoint creates a new webhook and subscribes it to specific events. After the retrieving the available events, create a webhook by passing the required body parameters.

📘
Note that by default a webhook is ENABLED when it is created.

Request Body

Parameter	Type	Required	Description
`url`	string	✅ Yes	The webhook URL where events should be sent.
`enabled_events`	array	✅ Yes	A list of events that trigger this webhook.

Example cURL Request

curl --location 'http://api.sandbox.waza.co/lync/client-webhooks' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "url": "https://api.example.com/webhooks/callforward",
    "enabled_events": [
        "banking.transfer.created",
        "banking.transfer.completed"
    ]
}'

Example Response

{
  "data": {
    "id": "18b6c1b9-73eb-4810-a2b3-2eb431714bd3",
    "created_at": "2025-03-22T23:30:15.125Z",
    "updated_at": "2025-03-22T23:30:15.125Z",
    "state": "ENABLED",
    "url": "https://api.example.com/webhooks/callforward",
    "enabled_events": [
      "banking.transfer.created",
      "banking.transfer.completed"
    ]
  }
}

3. Retrieve All Webhooks

This endpoint retrieves all configured webhooks, including their status, endpoint URL, and subscribed events.

Example Request

curl --location 'http://api.sandbox.waza.co/lync/client-webhooks' \
--header 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
  "data": {
    "items": [
      {
        "id": "16b8c1b9-73eb-4810-a2b3-2eb431714bd3",
        "created_at": "2025-03-22T22:28:23.451Z",
        "updated_at": "2025-03-22T22:28:23.451Z",
        "state": "ENABLED",
        "url": "https://api.example.com/webhooks/callforward",
        "enabled_events": [
          "banking.transfer.created",
          "banking.transfer.completed"
        ]
      }
    ],
    "page": 1,
    "limit": 10,
    "total_items": 1,
    "total_pages": 1
  }
}

Response Fields

Field	Type	Description
`id`	string	The unique webhook ID.
`created_at`	string	The timestamp when the webhook was created.
`updated_at`	string	The timestamp when the webhook was last updated.
`state`	string	The status of the webhook (`ENABLED`, `DISABLED`).
`url`	string	The webhook URL where events are sent.
`enabled_events`	array	The list of events that trigger the webhook.

4. Retrieve a Single Webhook

This endpoint retrieves details about a specific webhook, identified by its unique id. You can get information and perform actions with the webhooks by retrieving it all you need is do is pass the Webhook id as a query parameter.

Path Parameter

Parameter	Type	Required	Description
`id`	string	✅ Yes	The unique identifier of the webhook.

Example Request

curl --location 'http://api.sandbox.waza.co/lync/client-webhooks/8a525d95-5d18-4471-828c-90cef757ed09' \
--header 'Authorization: Bearer YOUR_API_KEY'

Example Response

{
  "data": {
    "id": "8a525d95-5d18-4471-828c-90cef757ed09",
    "created_at": "2025-03-22T21:18:18.665Z",
    "updated_at": "2025-03-22T22:53:49.258Z",
    "state": "DISABLED",
    "url": "https://api.example.com/webhooks/callback",
    "enabled_events": [
      "banking.transfer.created",
      "banking.transfer.completed"
    ]
  }
}

Response Fields

Field	Type	Description
`id`	string	The unique webhook ID.
`created_at`	string	The timestamp when the webhook was created.
`updated_at`	string	The timestamp when the webhook was last updated.
`state`	string	The status of the webhook (`ENABLED`, `DISABLED`).
`url`	string	The webhook URL where events are sent.
`enabled_events`	array	The list of events that trigger the webhook.