Event webhooks

An event webhook sends an HTTPS POST to your system the moment something happens in IconEngage, such as a customer's message or a delivery receipt. Each delivery is signed so you can check it came from IconEngage.

Event webhooks send events out to your system. To have your system start a flow in IconEngage, use Inbound webhooks instead.

Before you start

Every webhook is signed for one of your API keys and only sends what that key is allowed to read. So create an API key first. The key needs, for example, messages.read for message events.

Your endpoint must be a public https:// address.

Create a webhook

1. Go to Settings › Event webhooks.
2. Click New webhook.
3. In Name, enter a name (up to 120 characters).
4. In Endpoint URL, enter your https:// address.
5. In Sign for API key, choose the key the webhook belongs to. You cannot change this later.
6. Under Events, tick the events you want (see below).
7. Click Create webhook.
8. If asked, confirm your identity with your two-factor code or password.
9. Copy the secret from Copy your signing secret now and store it safely. You need it to verify signatures.
10. Click I have copied it.

If the chosen key cannot read what an event sends, the form says which permission it needs. Choose another key or drop that event.

Events you can subscribe to

Public API events

These have the documented body described below.

Automation events

You can also subscribe to the events that start automation flows: Message received, Conversation opened, Tag added, Tag removed, Field changed, Intent detected, Conversation attributed, Order placed, Payment received, Payment failed and Cart abandoned. Their bodies differ from the public API events. Message received here is not the same as API: message received.

What a delivery looks like

Each public API event is a POST with a JSON body:

{
  "id": "0b8f6a52-…",
  "type": "message.status",
  "version": 1,
  "occurred_at": "2026-10-11T09:31:12Z",
  "data": {
    "message": { "id": "6f1c2e8a-…", "wamid": "wamid.HBg…", "type": "template", "template_name": "order_confirmation" },
    "status": "delivered",
    "timestamp": "2026-10-11T09:31:12Z",
    "conversation": { "id": "b0e4…", "contact_id": "2a7d…", "phone_number_id": "1234567890" },
    "contact": { "id": "2a7d…", "wa_id": "919876543210", "display_name": "Asha" },
    "failure": null
  }
}

• id is the event's id. It is the same on every retry and replay, so use it to ignore events you have already handled.
• version is the version of data's shape. A change that could break your code would come as a new version.
• data.test is true on a test event and absent otherwise.
• Events carry ids and states, never secrets or file contents.

Each delivery also carries these headers:

Responding, retries and ordering

• Answer with any 2xx status within 10 seconds to accept a delivery. The response body is ignored.
• Any other answer, a timeout or a connection failure is retried with growing gaps (starting at 30 seconds and doubling, at most 6 hours apart), up to 8 attempts. After that the delivery is marked Dead letter and can be replayed.
• Delivery is at least once: you may receive the same event more than once. Dedupe on id.
• Events can arrive out of order. Use occurred_at to order them.

Manage your webhooks

The Event webhooks list shows each webhook's Name, Sends to, Events, Signed for and Status.

• Turn a webhook on or off with the switch in Status (On / Off).
• Suspended: IconEngage pauses a webhook that keeps failing, and says why (for example "Paused after too many failed deliveries"). Fix the cause, then turn it on again. That resumes sending and resets the failure count.
• Edit changes the name, endpoint and events. Delete stops events at once.

Check deliveries and replay one

1. Go to Settings › Event webhooks.
2. Open the webhook's actions menu and choose Delivery log.
3. Filter by Status if you want: Waiting, Sending, Delivered, Failed or Dead letter.

Each delivery shows every attempt with its time, your system's response code and how long it took. Bodies are never stored, so none are shown.

To try a delivery again:

1. Click Replay on the delivery.
2. Click Replay to confirm.

The replay is a new attempt of the same delivery, with the same event id. Earlier attempts stay in the log. A delivery that is still waiting or sending cannot be replayed.

Send a test event

Use a test event to check your endpoint and your signature check without waiting for real activity.

1. Open the webhook's Delivery log.
2. Choose one public API event, or Every API event it lists.
3. Click Send test event.

The test is a sample of the event with made-up values and data.test set to true. It reads none of your data. It is signed and logged like a real event and appears in the log with a Test badge. The webhook must be on. Test events exist for the public API events only, not for automation events.

Manage webhooks from the API

A key can also create, change, delete and test its own subscriptions with /webhook-subscriptions. See The IconEngage public API.