Skip to main content

Webhook

Use Webhooks to receive events to notify you when a variety of interactions or events happen.

note

The webhook integration is not enabled by default.

For more details on how to enable it, refer to our Configuration Section.

The webhook integration enables you to programmatically participate in conversations by sending messages or reacting to them. Here's a common integration pattern:

You must de-duplicate messages on arrival as the webhook does not guarantee events uniqueness.

Subscribing#

POST /webhooks.subscribe

Subscribes the webhook for the first time or update its parameters.

Sample request

{
"url": "https://my-url-to-be-hit",
"headers": {
"X-Custom-Header": "custom-code-for-header"
}
}

Sample response

{
"url": "https://my-url-to-be-hit",
"headers": {
"X-Custom-Header": "custom-code-for-header"
},
"status": "Subscribed",
"api_secret": "{UUID}"
}

Unsubscribing#

POST /webhooks.unsubscribe

Sample response

{
"url": "https://my-url-to-be-hit",
"headers": {
"X-Custom-Header": "custom-code-for-header"
},
"status": "Unsubscribed",
"api_secret": "{UUID}"
}

Info#

POST /webhooks.info

Sample response

{
"status": "Subscribed",
"url": "https://my-url-to-be-hit",
"headers": {
"X-Custom-Header": "custom-code-for-header"
}
}

Event Payloads#

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#

{
"type": "message",
"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": "{string}",
//'yyyy-MM-dd'T'HH:mm:ss.SSSZ' date in UTC form, to be localized by clients
"source": "{String}"
// one of the possible sources
}
}
}

Metadata#

Sample payload

{
"type": "metadata",
"payload": {
"subject": "conversation|channel|message",
"identifier": "conversation/channel/message id",
"metadata": {
// nested metadata object. I.e. for a conversation:
"contact": {
"displayName": "Grace"
},
"isUserTyping": true
}
}
}
Last updated on