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"
    }
  }
}
Webhook 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.
Organisation
organisation_updated
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",
  }
}
Brand
brand_updated
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",
  }
}
Project
project_updated
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",
  }
}
Event
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_updated
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"
  }
}
event_deleted
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"
  }
}
Event template
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"
  }
}
event_template_updated
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"
  }
}
event_template_deleted
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"
  }
}
Elements
element_created
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"
  }
}
element_update
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"
  }
}
element_deleted
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
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