Event Webhooks

Example Event Webhook Create Request

cURL

$ curl https://api.intercom.io/subscriptions \
-XPOST \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d'
{
  "service_type": "web",
  "topics": ["event.created"],
  "url": "https://example.org/hooks/1",
  "metadata": { 
    "event_names": ["invited-friend"]
  }
}'

cURL HTTP Response

HTTP/1.1 200 Ok

{
  "type": "notification_subscription",
  "id": "nsub_6ab4c480-fd8b-11e3-958f-c779cae3e1b3",
  "created_at": 1392731331,
  "updated_at": 1392731331,
  "service_type": "web",
  "topics": ["event.created"],
  "url": "https://example.org/hooks",
  "active": true,
  "hub_secret": null,
  "metadata" :{
    "event_names": ["invited-friend"]
  }
}

📘

Event webhooks are in Beta.

We'll be refining the API for a short while before lifting the beta tag, and we'd love to know what you think. Please send any feedback, questions or bug reports to us using the Intercom Messenger below!

Notes:

• The initial beta support does not limit to number of event names per topic, but this may be changed before moving out of Beta.
• We'll be adding support for event webhook subscriptions in the PHP, Ruby, Go, Node and Java clients.

Create an Event Webhook Subscription

To subscribe to event webhooks, add the event.created topic to your subscription in the topics field.

The names of the events must also be supplied in the subscription. This can be done by posting an array called event_names in the metadata field of the subscription. The event_names array is required for an events subscription - there is no option to subscribe to all event names.

Apart from the need to declare the event names, the event.created is a regular webhook and can be used with other topics in the same subscription.

Update an Event Webhook Subscription

You can update a subscription's event names by submitting a POST to the subscription's URL as described in Create a Subscription along with an updated event_names array. Note that the updated array replaces the existing array - the entire set of event names you want to subscribe to should be sent in an update.

Event Webhook Model

Example Event Notification Object

JSON

{
  "type": "notification_event",
  "topic": "event.created",
  "id": "notif_ccd8a4d0-f965-11e3-a367-c779cae3e1b3",
  "created_at": 1392731331,
  "delivery_attempts": 1,
  "first_sent_at": 1392731392,
  "data": {
    "item": {
      "type": "event",
      "id": "e5cc5f72-5522-11e4-9a06-49b58bcd0509",
      "event_name" : "invited-friend",
      "created_at": 1389913941,
      "user_id": "314159",
      "metadata": {
         "invitee_email": "[email protected]",
         "invite_code": "ADDAFRIEND"
      }
    }
  }
}

As with other topics, events sent to a webhook are published inside a Notification Object.

As well as the regular fields that were created when the event was posted to Intercom (see Event Object for details) the event payload will also contain an id field that uniquely identifies the event.