DocsBuilding AppsInstalling IntercomAPI & Webhook ReferenceCanvas Kit Reference
DocsApp StoreForumBlogYour Apps

Webhook notifications

A Webhook notification is the object delivered when an event is triggered, and notifications have data payloads that contain references to the Intercom objects associated with the event. There may be instances when we pause, suspend or delay notifications.

Why are my Webhook topic notifications missing?

Paused subscription notifications

If your endpoint URL responds with more than 1000 consecutive HTTP error codes in a 15-minute window, we pause your Webhook topic notifications for 15 minutes after which we start sending as normal again.

Suspended subscriptions

If your endpoint URL responds with HTTP error codes for more than seven days, we suspend your Webhook subscription, and you will stop receiving any further notifications.

If we suspend your subscription, we display an error banner on the Webhooks page under the Configure menu of the relevant App in your Developer Hub.

10201020

After resolving any issues with your server, you can resume suspended subscriptions by pressing Set live from the top right of the page.

We only suspend Webhook subscriptions for Private apps. Webhook subscriptions used in Public apps are never suspended.

Why are my Webhook topic notifications delayed?

Rate limiting

We will prioritise the first 150,000 events per minute of your Webhook topic notifications and then rate limit all further notifications with a lower priority.

Slow topic notifications

We prioritise Webhook topic notifications for endpoint URLs that successfully respond within 500ms. If response times exceed 500ms, we deliver topic notifications with a lower priority.

Throttling

If we receive an HTTP 429 (Too Many Requests) response from your endpoint URL, we throttle further notifications with a delay that starts at 1 minute and extends to 2 hours. We drop any throttled notifications if we do not receive a successful response within 2 hours.

Why are my Webhook topic notifications out of order?

Each notification object has a timestamp created_at field. We do not offer any guarantee on the order of Webhook topic notifications.

What happens to my Webhook topic notifications when Intercom is down?

If Intercom's System Status interrupts notification delivery, we will store them and resume sending once we restore the service. We will always prioritise the most recent notifications and process older delayed notifications with a lower priority.

What volume of notifications should I expect?

Events in Intercom with the potential for generating a high volume of Webhook topic notifications are related to the Content Stat object and Contact object.

For example, the volume of Content Stat Webhook topic notifications is typically five times the size of the audience receiving the Outbound Message content; Chats, Emails, Mobile Push etc.

Configure your endpoint URL server to handle spikes in velocity and volume to minimise paused and suspended Webhook subscriptions or rate-limited and throttled Webhook topic notifications.

Why am I receiving duplicate notifications?

If we do not receive an HTTP 200 (OK) response within 5 seconds of sending a notification, we will resend the notification one more time.

To avoid this, we recommend responding with HTTP 200 (OK) immediately upon receipt and before you trigger any long-running tasks.