Webhooks
Webhooks let an external application be notified automatically by MobiCRM when an event occurs. MobiCRM then sends a POST request in JSON format to the URL you registered.
Authentication
Webhooks are managed through the MobiCRM API (/openapi/v1/webhooks) and require a MobiCRM authentication token. To test from the interface, see the Swagger page.
A webhook is linked to the user who creates it. MobiCRM only sends items that are visible to this user: a contact, call or ticket they cannot access is never sent.
Creating a subscription
POST /openapi/v1/webhooks
{
"hookUrl": "https://mon-application.com/webhooks/mobicrm",
"eventTypes": ["TicketCreated", "PhoneCallCreated"]
}hookUrl: URL that will receive the events.eventTypes: list of the desired events (see the table below). UseAllto receive all events, including those added later.
The response (201) contains the identifier of the created webhook:
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }Listing subscriptions
GET /openapi/v1/webhooks
Returns the active webhooks of the authenticated user, sorted by creation date:
[
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"hookUrl": "https://mon-application.com/webhooks/mobicrm",
"eventTypes": ["TicketCreated", "PhoneCallCreated"],
"creationDate": "2024-01-15T10:00:00Z"
}
]Viewing a subscription
GET /openapi/v1/webhooks/{webhookId}
Returns the webhook in the same format as above, or 404 if it does not exist, has been deleted or belongs to another user.
Deleting a subscription
DELETE /openapi/v1/webhooks/{webhookId}
After deletion, no more events are sent to the URL concerned. Only the owner of the webhook can delete it: an attempt on another user's webhook returns a 400 error.
Available events
The up-to-date list of events is available via GET /openapi/v1/webhooks/eventtypes:
["All", "AccountCreated", "ContactCreated", "CampaignCreated", "PhoneCallCreated", "TicketCreated"]| Event | Triggered when | Content of data | Sent if |
|---|---|---|---|
All | All events | Depends on the event | Depends on the event |
AccountCreated | An account is created | Account (same format as the OpenAPI Account API) | The account is visible to the webhook owner |
ContactCreated | A contact is created | Contact (same format as the OpenAPI Contact API) | The contact is visible to the webhook owner |
CampaignCreated | A campaign is created | Campaign | Always |
PhoneCallCreated | A call is created | Phone call (same format as the OpenAPI Call API) | The call's contact is visible to the webhook owner, or the call has no contact |
TicketCreated | A ticket is created | Ticket (same format as the OpenAPI Ticket API) | The ticket is accessible to the webhook owner (accessible account or contact, or ticket assigned to them) |
Format of received requests
Each call is a POST with the Content-Type: application/json header. The body contains the event type and the data, with property names in camelCase:
{
"eventType": "PhoneCallCreated",
"data": {
"id": "0f8fad5b-d9cb-469f-a165-70867728950e",
"contactId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"ownerId": "1b4e28ba-2fa1-11d2-883f-0016d3cca427",
"direction": "Inbound",
"startDate": "2024-01-15T10:00:00Z",
"endDate": "2024-01-15T10:02:00Z",
"duration": 120,
"ownerPhone": "0102030405",
"contactPhone": "0607080910",
"isAnswered": true,
"phoneSystem": "Aircall",
"phoneSystemExternalId": "aircall-id",
"externalId": null,
"creationDate": "2024-01-15T10:02:05Z"
}
}Good to know
- Your URL must respond with an HTTP
2xxcode. In case of failure, the error is logged on the MobiCRM side and the delivery is not retried: the event is lost for this subscriber. - The order in which events arrive is not guaranteed.
- A subscription cannot be modified: delete it, then create it again.
