Managing webhooks over the API

Everything you can do on the Settings > Integrations > Webhooks screen can also be done through the API, so an integration can register its own endpoint without anyone opening the dashboard.

All requests need a bearer token, and the token owner needs the matching team permission. See Webhooks overview for the plan requirements and the lifecycle these endpoints drive.

Headers

{
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer {Your key here}"
}

The webhook object

{
    "id": 12,
    "URL": "https://yourdomain.com/alaaqat-webhook",
    "secret": "8f2c1d9b4a7e6035c1d8b2f4a9e7c603",
    "is_validated": true,
    "is_active": true,
    "consecutive_failures": 0,
    "last_failure_at": null,
    "account_id": 1,
    "created_at": "2026-08-27T10:15:00.000000Z",
    "updated_at": "2026-08-27T10:22:31.000000Z",
    "events": [
        {
            "id": 41,
            "name": "contact-created",
            "webhook_id": 12,
            "created_at": "2026-08-27T10:15:00.000000Z",
            "updated_at": "2026-08-27T10:15:00.000000Z"
        }
    ]
}
Field Description
URL Your HTTPS endpoint.
secret The 32 character secret key used to answer the validation challenge. Generated by Alaaqat; it cannot be set or changed.
is_validated Whether the endpoint answered the validation challenge correctly.
is_active Whether deliveries are switched on. Events are sent only when both is_validated and is_active are true.
consecutive_failures How many deliveries in a row have used up all their attempts. Any successful delivery resets it to 0, and reaching 3 switches is_active off. Read-only.
last_failure_at When the last delivery ran out of attempts, or null if none ever has. Read-only.
events The events this webhook is subscribed to.

List webhooks

GET https://app.alaaqat.com/api/account/webhooks

Returns every webhook of the current account. Requires the webhook-index permission.

Response

{
    "data": [
        {
            "id": 12,
            "URL": "https://yourdomain.com/alaaqat-webhook",
            "secret": "8f2c1d9b4a7e6035c1d8b2f4a9e7c603",
            "is_validated": true,
            "is_active": true,
            "consecutive_failures": 0,
            "last_failure_at": null,
            "account_id": 1,
            "created_at": "2026-08-27T10:15:00.000000Z",
            "updated_at": "2026-08-27T10:22:31.000000Z",
            "events": [
                {
                    "id": 41,
                    "name": "contact-created",
                    "webhook_id": 12,
                    "created_at": "2026-08-27T10:15:00.000000Z",
                    "updated_at": "2026-08-27T10:15:00.000000Z"
                }
            ]
        }
    ]
}

Create a webhook

POST https://app.alaaqat.com/api/account/webhooks

Requires the webhook-create permission.

Body

{
    URL: string,
    events: string[]
}
Field Required Validation Description
URL Required A valid URL using https The endpoint that will receive the deliveries
events Required array, at least one element The events to subscribe to
events.* Required One of the available events Event name, for example contact-created

account_id, is_validated and is_active are rejected if sent — a new webhook always starts unvalidated and inactive, and the secret is generated for you.

{
    "URL": "https://yourdomain.com/alaaqat-webhook",
    "events": ["contact-created", "contact-updated", "deal-created"]
}

Response

201 Created, returning the new webhook including its secret.

{
    "data": {
        "id": 12,
        "URL": "https://yourdomain.com/alaaqat-webhook",
        "secret": "8f2c1d9b4a7e6035c1d8b2f4a9e7c603",
        "is_validated": false,
        "is_active": false,
        "consecutive_failures": 0,
        "last_failure_at": null,
        "account_id": 1,
        "created_at": "2026-08-27T10:15:00.000000Z",
        "updated_at": "2026-08-27T10:15:00.000000Z",
        "events": [
            {
                "id": 41,
                "name": "contact-created",
                "webhook_id": 12,
                "created_at": "2026-08-27T10:15:00.000000Z",
                "updated_at": "2026-08-27T10:15:00.000000Z"
            }
        ]
    },
    "message": "Entity was created successfully."
}

Errors

Code Meaning
402 Your plan does not include webhooks, or you already reached the maximum number of webhooks.
422 The URL is not a valid https address, or one of the events does not exist.

Update a webhook

PUT https://app.alaaqat.com/api/account/webhooks/{id}

Where id is the webhook id. Requires the webhook-update permission.

The body is identical to the create body, and events replaces the current subscription list — send the full list you want to keep, not just the additions.

{warning} Changing URL sets is_validated back to false, and deliveries stop until you validate the webhook again.

Response

200 OK with the updated webhook and the message Entity was modified successfully.

Validate a webhook

POST https://app.alaaqat.com/api/account/webhooks/{id}/validate

Sends the challenge to your endpoint. Requires the webhook-update permission. No body.

Read Validating your endpoint for the exact answer your endpoint must return.

Response

200 OK with the webhook, now carrying "is_validated": true.

If the endpoint did not answer correctly, the webhook stays unvalidated and the response is:

{
    "message": "Unable to validate the webhook. Please ensure that the secret key is correct and the webhook endpoint is properly configured."
}

with status 403.

Activate or deactivate a webhook

PUT https://app.alaaqat.com/api/account/webhooks/{id}/activate

Requires the webhook-update permission, and the webhook must already be validated — otherwise the request is rejected with 403.

Body

{
    "is_active": true
}
Field Required Validation Description
is_active Required boolean true starts deliveries, false stops them

This is also how you bring back a webhook that Alaaqat switched off after repeated failures: the webhook stays validated, so a single is_active: true call is all it takes once your endpoint is healthy again.

Response

200 OK. The response carries no useful body; read the webhook back with the list endpoint if you need to confirm the new state.

Delete a webhook

DELETE https://app.alaaqat.com/api/account/webhooks/{id}

Requires the webhook-delete permission. The webhook and its event subscriptions are removed permanently and deliveries stop immediately.

Response

{
    "message": "Entity was deleted successfully.",
    "data": []
}

A full example

# 1. create the webhook
curl -X POST https://app.alaaqat.com/api/account/webhooks \
  -H "Authorization: Bearer {Your key here}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"URL":"https://yourdomain.com/alaaqat-webhook","events":["contact-created","contact-updated"]}'

# 2. validate it (your endpoint must answer the challenge)
curl -X POST https://app.alaaqat.com/api/account/webhooks/12/validate \
  -H "Authorization: Bearer {Your key here}" \
  -H "Accept: application/json"

# 3. activate it
curl -X PUT https://app.alaaqat.com/api/account/webhooks/12/activate \
  -H "Authorization: Bearer {Your key here}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"is_active":true}'