Webhooks
Webhooks mechanism allows platform integrations by subscribing to certain Events. When the Event is triggered, the platform sends an HTTP POST request with the payload to the configured webhook URL.
To change existing subscriptions, the handshake can be repeated with a different response body.
Here are some requirements and tips for webhook receiver endpoints:
- An endpoint must respond with HTTP 200 (OK). Otherwise, webhook delivery is retried.
- Webhook endpoint should respond as quickly as possible. If response time exceeds the predefined duration (5 seconds currently), delivery is considered as failed and retried. If heavy processing is possible within the endpoint routine, it is worth extracting it into background processing (queue).
Webhook delivery is considered as failed in such cases:
- network error
- response code is not 200 OK
- it took too long for the receiver to respond (timeout)
In case of failure, delivery is retried. Currently, there are 5 attempts in total to deliver the webhook, with 3 seconds interval between each.
Each event payload has an ID parameter that uniquely identifies the triggered webhook event. It is the same for every delivery retry, so it can be used to guarantee that a specific event is processed once at most.
Event payload of any type has the following schema:
Property | Format | Description |
id | string (UUID) | Unique identifier of the triggered webhook event |
ts | number | Timestamp of emitted event, in milliseconds |
type | string | Webhook event type; Possible options are described below |
payload | object | An object containing event type-specific payload |
Example
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ts": 1613718881527,
"type": "event_created",
"payload": {
"event": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Event name",
"source_event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"project": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Project name"
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Brand name"
},
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Organisation name"
}
}
}
Note that only payload schemas and examples are provided below. The whole structure of the webhook request body is described in Webhook body schema section.
Triggered when an Organisation is updated in Studio.
Payload schema
Property | Format | Description |
organisation.id | string (UUID) | Organisation ID |
Payload example
{
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
}
}
Triggered when a Brand is updated in Studio.
Payload schema
Property | Format | Description |
organisation.id | string (UUID) | Organisation ID |
brand.id | string (UUID) | Brand ID |
Payload example
{
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
}
}
Triggered when a Project is updated in Studio.
Payload schema
Property | Format | Description |
project.id | string (UUID) | Project ID |
brand.id | string (UUID) | Brand ID |
organisation.id | string (UUID) | Organisation ID |
Payload example
{
"project": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
},
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
}
}
Triggered when an Event is created in Studio.
Payload schema
Property | Format | Description |
event.id | string (UUID) | Event ID |
event.name | string | Event name |
event.source_event_id | string (UUID) | Experience source event/template ID |
project.id | string (UUID) | Project ID |
project.name | string | Project name |
brand.id | string (UUID) | Brand ID |
brand.name | string | Brand name |
organisation.id | string (UUID) | Organisation ID |
organisation.name | string | Organisation name |
Payload example
{
"event": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Event name",
"source_event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"project": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Project name"
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Brand name"
},
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Organisation name"
}
}
Triggered when an Event is updated in Studio.
Payload schema
Property | Format | Description |
event.id | string (UUID) | Event ID |
event.source_event_id | string (UUID) | Experience source event/template ID |
project.id | string (UUID) | Project ID |
brand.id | string (UUID) | Brand ID |
organisation.id | string (UUID) | Organisation ID |
Payload example
{
"event": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"source_event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"project": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
}
Triggered when an Event is deleted in Studio.
Payload schema
Property | Format | Description |
event.id | string (UUID) | Event ID |
event.source_event_id | string (UUID) | Experience source event/template ID |
project.id | string (UUID) | Project ID |
brand.id | string (UUID) | Brand ID |
organisation.id | string (UUID) | Organisation ID |
Payload example
{
"event": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"source_event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"project": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
}
Triggered when an Event template is created in Studio.
Payload schema
Property | Format | Description |
event_template.id | string (UUID) | Event template ID |
event_template.name | string | Event template name |
event_template.source_event_id | string (UUID) | Experience source event/template ID |
project.id | string (UUID) | Project ID |
project.name | string | Project name |
brand.id | string (UUID) | Brand ID |
brand.name | string | Brand name |
organisation.id | string (UUID) | Organisation ID |
organisation.name | string | Organisation name |
Payload example
{
"event_template": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Event template name",
"source_event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"project": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Project name"
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Brand name"
},
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Organisation name"
}
}
Triggered when an Event template is updated in Studio.
Payload schema
Property | Format | Description |
event_template.id | string (UUID) | Event template ID |
event_template.source_event_id | string (UUID) | Experience source event/template ID |
project.id | string (UUID) | Project ID |
brand.id | string (UUID) | Brand ID |
organisation.id | string (UUID) | Organisation ID |
Payload example
{
"event_template": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"source_event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"project": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
}
Triggered when an Event template is deleted in Studio.
Payload schema
Property | Format | Description |
event_template.id | string (UUID) | Event template ID |
event_template.source_event_id | string (UUID) | Experience source event/template ID |
project.id | string (UUID) | Project ID |
brand.id | string (UUID) | Brand ID |
organisation.id | string (UUID) | Organisation ID |
Payload example
{
"event_template": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"source_event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"project": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
}
Triggered when an Element is created in Studio.
Payload schema
Property | Format | Description |
element.id | string (UUID) | Element ID |
event_template.id | string (UUID) | Event template ID (if the element belongs to a template) |
event.id | string (UUID) | Event ID (if the element belongs to an event) |
project.id | string (UUID) | Project ID |
brand.id | string (UUID) | Brand ID |
organisation.id | string (UUID) | Organisation ID |
Payload example
{
"element": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
},
"event": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
},
"project": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
}
Triggered when an Element is updated in Studio.
Payload schema
Property | Format | Description |
element.id | string (UUID) | Element ID |
event_template.id | string (UUID) | Event template ID (if the element belongs to a template) |
event.id | string (UUID) | Event ID (if the element belongs to an event) |
project.id | string (UUID) | Project ID |
brand.id | string (UUID) | Brand ID |
organisation.id | string (UUID) | Organisation ID |
Payload example
{
"element": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
},
"event": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
},
"project": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
}
Triggered when an Element is deleted in Studio.
Payload schema
Property | Format | Description |
element.id | string (UUID) | Element ID |
event_template.id | string (UUID) | Event template ID (if the element belongs to a template) |
event.id | string (UUID) | Event ID (if the element belongs to an event) |
project.id | string (UUID) | Project ID |
brand.id | string (UUID) | Brand ID |
organisation.id | string (UUID) | Organisation ID |
Payload example
{
"element": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
},
"event": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
},
"project": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"brand": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"organisation": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
}
Last modified 10mo ago