Webhooks

Webhooks allow you to receive real-time updates when a specific event occurs, i.e. message is received from a contact. These events are HTTP POST requests being sent to an endpoint of your server. Similarly to Amio Messaging API, body of such request is in JSON format. All events which happen in a specific channel are delivered to a single webhook url (i.e. https://your-server.com/webhook) which you can set in administration.

When you receive a webhook event, you should always return HTTP response in 2xx class, i.e. 200 OK in shortest time possible (we close the connections which takes longer then 60 seconds). If the webhook request fails or exceeds the maximum time, Amio will try to re-deliver the webhook again later (see Webhook Re-Delivery).

📘

Set Webhook URL

  1. Login to app.amio.io.
  2. Pick a channel from channels.
  3. Select tab Webhook and set Webhook Url.

Webhook Content

All webhooks have following body structure:

{
  "event": "{{EVENT_NAME}}",
  "timestamp" : "{{ISO_8601_TIMESTAMP}}",
  "data" : {
    "{{event type specific data}}"
  }
}

Parameter

Type

Description

event

string

Event type name. See Events for complete list of events emitted by Amio.

timestamp

string

Iso 8601 Timestamp - time when we sent you the webhook.

data

object

Event type specific data object.

Webhook Re-Delivery

If your webhook fails with response code 4xx or 5xx, Amio will try to re-deliver the webhook again. There are several re-delivery events after 1, 5, 20, 60, 180 and 480 minutes. If all retries fail, the webhook call is discarded.