Webhooks

Overview

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.

Subscription

Subscription to the events is configured during instance handshake.

To change existing subscriptions, the handshake can be repeated with a different response body.

Webhook receiver

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).

Error handling and retries

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.

Webhook body schema

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"
}
}
}

Event types and payloads

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.

event_created

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"
}
}

event_template_created

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"
}
}