Skip to main content

Webhook

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

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