Webhooks: Subscribing to Drift Events

Webhook events give you access to realtime information about what's happening in your Drift account. Instead of asking us for information on a regular basis, we'll tell you about events such as new messages and updated contacts.

Configuring Webhooks

To set up your webhooks, head to you app on dev.drift.com. Under the Events section, you can provide a request URL and choose the events you'd like us to inform you of.

📘

How can I receive events directly on my local computer?

Don't worry! You can use a tool called ngrok to send Drift webhook events directly to your computer and test your application. Find out more information in our guide

Verification Token

Under App Credentials, you'll see a field titled Verification Token . You can use this token to verify that the data being sent to your endpoint is actually from Drift.

We include this token in every event we send to you as:

  • a token field in the body
  • a header called X-Verification-Token

If your token does get compromised, you can re-generate it on your App Credentials page.

👍

Securing by IP Address

Drift broadcasts should originate from one of these IP addresses:
34.235.12.14
52.45.108.163
52.54.36.148
52.202.79.180

Request format

When an event occurs, we'll send an HTTPS POST request to your configured request URL. The JSON payload we send will include three top-level attributes:

  • type - the type of event (see Event Types below)
  • token - your verification token which can be found on the App Credentials page (see above)
  • orgId - the organization the event is for
  • data - the data associated with the event (a contact, a message, etc)
{
  "type": the_event_type,
  "token", string,
  "orgId": int,
  "data": {
    ...
  }
}

Event types

🚧

conversation_status_updated has been deprecated!

The conversation_status_updated event is being phased out of the Drift developer platform. Your app may need to be updated! Please see Webhooks: Deprecating Conversation Status for more details

Event Type

Description

Required Scope

contact_identified

A contact added their email in chat

contact_read

new_message

A new message was created

conversation_read

new_command_message

A new command message was received. Currently these begin with a slash / - ex: /msg. This is a filtered, lower access, version of new_message. Recommended if your app only cares about a trigger phrase being sent in chat.

conversation_read

new_conversation

A new conversation was started. This explicitly looks at conversations not started by bots - i.e. a site visitor interaction with a welcome message.

conversation_read

conversation_status_updated

The status of the conversation has changed.

deprecated - use conversation_push or one of its source events

conversation_read

conversation_inactive

A conversation has not seen activity after a configurable period of time.

conversation_read

conversation_manual_push

Indicates that a conversation is ready to be consumed by listeners via a manual user action.

conversation_read

conversation_push

Combines events that indicate conversations are ready for consumption (conversation_manual_push and conversation_inactive)

conversation_read

conversation_participant_added

Participants were added to a conversation

conversation_read

conversation_participant_removed

Participants were removed from a conversation

conversation_read

button_clicked

A button was clicked in a conversation. The payload will include the contact id.

conversation_read

playbook_goal_met

his will fire whenever a goal is met with a previously identified contact (i.e. a site visitor that provided their email or is known in the Drift UI). The payload will include the contact id.

conversation_read

user_unsubscribed

A user unsubscribed from all emails - this is invoked whenever someone opts out of email communication (either manually, or by the api).

user_read

new_meeting

A meeting was booked by a contact or site visitor with a member of your team - scheduled by the bot or via your calendar schedule page. Requires calendar connection in drift.

conversation_read

meeting_updated

A previously booked meeting was either rescheduled or canceled.

conversation_read

contact_updated

A contact record has been updated in drift

all_contact_read

gdpr_delete_requested

A user requested a GDPR-deletion of a contact from drift privacy settings or the API.

gdpr_read

app_disconnected

A drift user (organization) disconnected your app.

no scope required

user_availability_updated

A drift user's availability has been changed.

user_read

phone_captured

A phone number was captured in a conversation

conversation_read

chat_to_call

A Drift user completed call with Chat to Call

conversation_read

📘

Getting Information on the connected account

If you want to determine who exists in a connecting organization's account, as well as who are the admins, we recommend using the GET Users endpoint to get a list of the Drift users in the account.

Example Webhook Data

New Message

{
  "orgId": int, // organization identifier (id value).
  "type": "new_message",
  "data": Message // See Message model page in docs.
}

New Command Message

{
  "orgId": int,
  "type": "new_command_message",
  "data": Message // See Message model page.
}

New Conversation

{
  "orgId": int,
  "type": "new_conversation",
  "data": Conversation // See Conversation Model page.
}

Conversation Status Update (deprecated)

Fires when a conversation changes statuses. This event is deprecated. Alternative events:
To receive new chat activity: use new_message
To know when to act on a conversation: use conversation_manual_push, conversation_inactive, or conversation_push
Please see Webhooks: Deprecating Conversation Status for more details

{
  "orgId": int,
  "type": "conversation_status_updated",
  "data": {
    "conversationId": long,
    "status": {open, closed, pending},
    "changedAt": long
  }
}

Conversation Inactive

Fired per conversation when no messages have been sent in that conversation for some period of time. The time period is configurable by admin users in the advanced conversation settings. For each new message a conversation, the event is rescheduled to be the configured amount of time after the latest message.

{
  "orgId": int,
  "type": "conversation_inactive",
  "data": {
    "lastUpdated": long,
    "conversationId": long
  }
}

Conversation Manual Push

Fired when a user takes an action to push a conversation to third-party applications. This includes:

  • When a conversation is closed (by a user or automatically via auto-close)
  • When the /sync command is used in the beta chat interface
{
  "orgId": int,
  "type": "conversation_manual_push",
  "data": {
    "conversationId": long,
    "pushedAt": long,
    "userId": long (optional)
  }
}

Conversation Push

When triggered, the conversation is ready for consumption by third-party applications. This event is for developer convenience and combines the conversation_inactive and conversation_manual_push events into one stream.

{
  "orgId": int,
  "type": "conversation_push",
  "data": {
    "source": conversation_inactive | conversation_manual_push,
    "data": (see `data` fields of the source event)
  }
}

Conversation Participant Added

{
  "orgId": int,
  "type": "conversation_participant_added",
  "data": {
    "conversationId": long,
    "addedParticipants": [int],
    "changedAt": long
  }
}

Conversation Participant Removed

{
  "orgId": int,
  "type": "conversation_participant_removed",
  "data": {
    "conversationId": long,
    "removedParticipants": [int],
    "changedAt": long
  }
}

Button Clicked

{
  "orgId": int,
  "type": "button_clicked",
  "data": Message // See Message model page in docs.
}

Contact Email Captured

{
  "orgId": int,
  "type": "contact_identified",
  "data": Contact // see Contact Model page.
}

Playbook Goal Met

{
  "orgId" : int,
  "type" : "playbook_goal_met",
  "data" : {
    "conversationId": long,
    "playbookId":  int,
    "contactId": long,
    "goalId": string,
    "goalName": string,
    "playbookName": string,
    "contactEmail": string
  }
}

User Unsubscribed

Will fire whenever a user unsubscribes

{
  "orgId": int,
  "type": "user_unsubscribed",
  "data": Contact // see Contact Model page.
}

New Meeting

{
  "orgId": int,
  "type":"new_meeting",
  "data": {
   "agentId": int (agent that received the meeting),
   "orgId": int,
   "status": string (ex: "ACTIVE", state of the meeting),
   "schedulerId": long (id of scheduling user or contact),
   "eventId": string (calendar event id),
   "slug": string (meeting slug identifier),
   "slotStart": long (timestamp),
   "slotEnd": long (timestamp),
   "scheduledAt": long (timestamp),
   "conversationId": long (present if meeting was booked from chat)  
  }
}

Meeting Updated

This webhook will be fired for rescheduled and canceled meetings.

{
  "orgId": int,
  "type":"meeting_updated",
  "data": {
   "eventType": string (one of "canceled" or "rescheduled"),
   "agentId": int (agent that received the meeting),
   "orgId": int,
   "schedulerId": long (id of scheduling user or contact),
   "eventId": string (calendar event id),
   "slug": string (meeting slug identifier),
   "slotStart": long (timestamp),
   "slotEnd": long (timestamp),
   "scheduledAt": long (timestamp),
   "conversationId": long (present if meeting was booked from chat)  
  }
}

Contact Updated

See document here: Contact Update Subscriptions

GDPR Delete Requested

{
  "orgId": int,
  "type":"gdpr_delete_requested",
  "data": {
    "email": string (email to purge),
    "requesterId": int (drift userId who initiated the delete request)
  }
}

App Disconnected

This webhook will fire when any drift customer or organization disconnects your application.

{
  "orgId": int,
  "type":"app_disconnected",
  "data": {
     "appId": string,
     "timestamp": long (timestamp), // time of disconnect
   }
}

User Availability Updated

This webhook will fire whenever a Drift user's availability changes. This is also testable by toggling availability here: https://app.drift.com/settings/team, and verifying you receive the webhook when active.

{
  "orgId": int,
  "type":"user_availability_updated",
  "data": {
     "userId": int, // id of the Drift User that changed
     "updatedAt": long (timestamp), // time of update
     "availability": string // new availability status, one of {ONLINE, AWAY, AVAILABLE}
   }
}

Phone Captured

This webhook will fire whenever a phone number is provided in a conversation. Supports international numbers, with some leniency in user-provided format.

{
  "orgId":1,
    "type":"phone_captured",
    "data": {
      "conversationId": long, // conversation id where the message was posted
      "authorId": long, // id of the user or contact that sent the message
      "authorType": string, // type of message sender, {contact, user}
      "phoneNumber": string // phone number provided, ex: "555-444-6666"
    }
}

Chat to Call

This webhook will fire a Drift user completes a phone call through Drift Chat to Call.

{
  "orgId":int,
  "type":"chat_to_call",
  "data":{
    "agentId":int,
    "endUserId":long,
    "orgId":int,
    "eventId":string,
    "conversationId":long,
    "startedAt":long,
    "endedAt":long, 
    "updatedAt":long,
    "bridgedAt":long, // not present for calls made through the browser
    "instantMeetingSource":string,
    "status":string,
    "agentPhone":string,
    "endUserPhone":string,
    "type":string // will be "PHONE_BRIDGE" or "BROWSER_CALL" for phone to phone 
                  // and browser calling respectively
  }
}

Updated 10 days ago

Webhooks: Subscribing to Drift Events


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.