Webhooks¶

Webhooks allow other applications to subscribe to specific events happening in EspoCRM and receive data related to those events. Webhooks are supposed to be created via API by other applications. The webhook has a specific Event and URL. Every time the event occurs, the system will send POST request with some payload to the specified URL.

Webhooks can be created only by API Users (via an API request) and Administrators. An API User has to have Webhooks scope enabled in Roles. An API User has also to have access to all entity types for which webhooks are intended to be created.

Subscription
Events
Webhook requests
Error handling
Signature checking
Config parameters
Debugging

Subscription¶

Creating request¶

POST api/v1/Webhook

{
    "event": "EVENT",
    "url": "URL"
}

A Webhook ID and a secret key will be sent back in a response:

id – an ID of created webhook,
secretKey – a generated secret key.

Deleting request¶

DELETE api/v1/Webhook/WEBHOOK_ID

Administration¶

An administrator can manage webhooks at Administration > Webhooks. It's possible to remove, edit or create webhooks there.

Events¶

Note

The list of available entity types can be obtained at Administration > Entity Manager.

ENTITY_TYPE.create¶

Triggered when a record is created. All record attributes will be sent in a payload.

Example: Account.create

ENTITY_TYPE.update¶

Triggered when a record is updated. Only updated record attributes will be sent in a payload.

Example: Account.update

ENTITY_TYPE.delete¶

Triggered when a record is removed.

Example: Account.delete

ENTITY_TYPE.fieldUpdate.FIELD¶

Triggered when a specific field is updated. New field attributes will be sent in a payload.

Example: Account.fieldUpdate.assignedUserId

Note

The list of available fields can be obtained at Administration > Entity Manager > fields.

Webhook requests¶

Every webhook request (sent by EspoCRM to a specified URL) is of POST type. A content type is application/json.

Events related to the same hook are sent in batches. The request payload is always an array (even if only one record is sent).

One event occurred:

[
    {
        "id": "someId",
        "name": "some name"
    }
]

Multiple events occurred:

[
    {
        "id": "someId1",
        "name": "some name 1"
    },
    {
        "id": "someId2",
        "name": "some name 2"
    }
]

Request sending is processed by the scheduled job Process Webhook Queue (Administration > Scheduled Jobs). By default, it runs every 5 minutes. You can change the scheduling.

Error handling¶

When EspoCRM is trying to send a webhook request and an error occurs, EspoCRM will process it the following ways:

errors 400, 401, 403, 404, 405, 408, connection timed out, or connection failed - will try to make another attempt;
error 410 - hook will be removed immediately.

Signature checking¶

It's possible to check the authenticity of a webhook request by comparing the signature passed in the X-Signature header with a value calculated on the server that receives the request.

Example for PHP:

$signature = base64_encode($webhookId . ':' . hash_hmac('sha256', $payload, $secretKey, true));

webhookId can be obtained from the response upon webhook creation or at Administration > Webhooks;
secretKey can be obtained from the response upon webhook creation or at Administration > Webhooks;
payload is a payload of the request.

Config parameters¶

Can be set manually in data/config.php.

webhookMaxCountPerUser = 50
webhookQueueEventPortionSize = 20
webhookQueuePortionSize = 20
webhookBatchSize = 50
webhookMaxAttemptNumber = 4
webhookFailAttemptPeriod = '10 minutes'
webhookConnectTimeout = 5 (seconds)
webhookTimeout = 10 (seconds)

Debugging¶

Queues are stored in two database tables: webhook_queue_item and webhook_event_queue_item. Webhook Queue Items are available from the UI at Administration > Webhooks > menu in the top-right corner > Webhook Queue Items.

You can enable debug mode to see more details in the log.