Webhook
Use Webhooks to get notified when events happen.
The webhook integration is not enabled by default.
For more details on how to enable it, refer to our Configuration Section.
The outbound webhook integration enables you to programmatically participate in conversations by sending messages or reacting to them. Here's a common integration pattern:
- Call the
subscribe
endpoint - Consume on your URL of choice events
- React to those events by calling the
send message
endpoint
You must de-duplicate messages on arrival as the webhook does not guarantee
events uniqueness. Your webhook also has to respond to every message with a status code of 200
.
Subscribing
POST /webhooks.subscribe
Subscribes the webhook for the first time or update its parameters.
Sample request
{
"url": "https://endpoint.com/webhook", // required
"id": "3e639566-29fa-450d-a59f-ae3c25d7260f",
"name": "Customer relationship tool",
"events": ["message.created", "message.updated", "conversation.updated", "channel.updated"],
"headers": {
"X-Custom-Header": "e.g. authentication token"
},
"signature_key": "secret-key-for-hmac-header"
}
url
Endpoint to be called when sending events.id
(optional) provide for updates.name
(optional) name to identify the webhook.headers
(optional) HTTP headers to set on each request (useful for authentication).signature_key
(optional) when set, the webhook will also send a headerX-Airy-Content-Signature
that contains the SHA256 HMAC of the specified key and the content.events
(optional) List of event types to receive. See below for a detailed list. Omit to receive all event types.
Sample response
{
"id": "3e639566-29fa-450d-a59f-ae3c25d7260f",
"name": "Customer relationship tool", // optional
"url": "https://endpoint.com/webhook", // optional
"events": [
// optional
"message.created",
"message.updated",
"conversation.updated",
"channel.updated"
],
"headers": {
// optional
"X-Custom-Header": "custom-code-for-header"
},
"status": "Subscribed"
}
Unsubscribing
POST /webhooks.unsubscribe
Sample response
{
"id": "3e639566-29fa-450d-a59f-ae3c25d7260f",
"name": "Customer relationship tool", // optional
"url": "https://endpoint.com/webhook", // optional
"events": [
// optional
"message.created",
"message.updated",
"conversation.updated",
"channel.updated"
],
"headers": {
// optional
"X-Custom-Header": "custom-code-for-header"
},
"status": "Unsubscribed"
}
Update
POST /webhooks.update
Update the webhook parameters.
Sample request
{
"id": "3e639566-29fa-450d-a59f-ae3c25d7260f", // required
"name": "Customer tool for relationship", // optional
"url": "https://endpoint.com/webhook", // optional
"events": ["message.created", "message.updated", "conversation.updated", "channel.updated"], // optional
"headers": {
"X-Custom-Header": "e.g. authentication token"
}, // optional
"signature_key": "secret-key-for-hmac-header" // optional
}
id
(required) provide for updatesurl
(optional) Endpoint to be called when sending events.headers
(optional) HTTP headers to set on each request (useful for authentication)signature_key
(optional) when set, the webhook will also send a headerX-Airy-Content-Signature
that contains the SHA256 HMAC of the specified key and the content.events
(optional) List of event types to receive. See below for a detailed list. Omit to receive all event types.
Sample response
{
"id": "3e639566-29fa-450d-a59f-ae3c25d7260f",
"name": "Customer tool for relationship", // optional
"url": "https://endpoint.com/webhook",
"events": [
// optional
"message.created",
"message.updated",
"conversation.updated",
"channel.updated"
],
"headers": {
// optional
"X-Custom-Header": "custom-code-for-header"
},
"status": "Subscribed"
}
List
POST /webhooks.list
List of subscribed webhooks.
{
"data": [
{
"name": "Customer relationship tool", // optional
"url": "https://endpoint.com/webhook",
"headers": {
// optional
"X-Custom-Header": "custom-code-for-header"
},
"status": "Subscribed"
},
{
"name": "Datalake connector", // optional
"url": "https://other-endpoint.com/webhook",
"events": ["conversation.updated"], // optional
"status": "Unsubscribed"
}
]
}
Info
POST /webhooks.info
Sample request
{
"id": "3e639566-29fa-450d-a59f-ae3c25d7260f"
}
Sample response
{
"id": "3e639566-29fa-450d-a59f-ae3c25d7260f",
"name": "Customer tool for relationship", // optional
"url": "https://endpoint.com/webhook",
"events": [
// optional
"message.created",
"message.updated",
"conversation.updated",
"channel.updated"
],
"headers": {
// optional
"X-Custom-Header": "custom-code-for-header"
},
"status": "Subscribed"
}
Events
After subscribing to an Airy webhook, you will start receiving events on your URL of choice. The event will always be a POST request with one the following payloads:
message.created
{
"type": "message.created",
"payload": {
"conversation_id": "{UUID}",
"channel_id": "{UUID}",
"message": {
"id": "{UUID}",
"content": {"text": "Hello World"}, // source message payload
"delivery_state": "pending|failed|delivered", // delivery state of message, one of pending, failed, delivered
"from_contact": true,
"sent_at": "2020-10-25T21:24:54.560Z", // ISO 8601 date string
"source": "facebook", // messaging source
// details about the sender
"sender": {
"id": "github:12345" // For unauthenticated instances this defaults to "airy-core-anonymous"
}
}
}
}
message.updated
Sent whenever a message is updated (e.g. delivery state) or its metadata changed.
{
"type": "message.updated",
"payload": {
"conversation_id": "{UUID}",
"channel_id": "{UUID}",
"message": {
"id": "{UUID}",
"content": {"text": "Hello World"}, // source message payload
"delivery_state": "pending|failed|delivered", // delivery state of message, one of pending, failed, delivered
"from_contact": false,
"sent_at": "2020-10-25T21:24:54.560Z", // ISO 8601 date string
"source": "facebook", // messaging source
"metadata": {
"source": {
"id": "facebook message id",
"delivery_state": "seen"
}
},
// details about the sender
"sender": {
"id": "github:12345" // For unauthenticated instances this defaults to "airy-core-anonymous"
}
}
}
}
conversation.updated
Sample payload
{
"type": "conversation.updated",
"payload": {
"id": "2e1da639-7152-4595-b43e-2117a55ac260",
"created_at": "2020-10-25T21:24:54.560Z", // ISO 8601 date string
"channel_id": "b9963564-1167-5b5f-9f61-7c1a82573320",
"metadata": {
"contact": {
"displayName": "Grace Hopper"
},
"isUserTyping": true
},
"last_message": {
"id": "{UUID}",
"content": {"text": "Hello World"}, // source message payload
"delivery_state": "pending|failed|delivered", // delivery state of message, one of pending, failed, delivered
"from_contact": true,
"sent_at": "2020-10-25T21:24:54.560Z", // ISO 8601 date string
"source": "facebook", // messaging source
// details about the sender
"sender": {
"id": "github:12345" // For unauthenticated instances this defaults to "airy-core-anonymous"
}
}
}
}
channel.updated
Sent whenever a channel is (un-) subscribed or its metadata changes.
{
"type": "channel.updated",
"payload": {
"id": "771b8bb5-c611-4979-bfd9-f10bbddfcf9b",
"source": "facebook",
"source_channel_id": "fb-page-id-1",
"metadata": {
"name": "My page 1",
"image_url": "http://example.org/avatar.jpeg" // optional
},
"connected": true
}
}