Guides
Dev.DriftGuides

Webhooks: Subscribing to Drift Events

Suggest Edits

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. Drift's outbound IP addresses are subject to change over time so this Verification Token is a more stable and future-proof way than IP whitelisting to secure your inbound webhook traffic.

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.

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

Event TypeDescriptionRequired Scope
contact_identifiedA contact added their email in chatcontact_read
new_messageA new message was createdconversation_read
new_command_messageA 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_conversationA 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_updatedThe status of the conversation has changed.

deprecated - use conversation_push or one of its source events		conversation_read
conversation_inactiveA conversation has not seen activity after a configurable period of time.conversation_read
conversation_manual_pushIndicates that a conversation is ready to be consumed by listeners via a manual user action.conversation_read
conversation_pushCombines events that indicate conversations are ready for consumption (conversation_manual_push and conversation_inactive)conversation_read
conversation_participant_addedParticipants were added to a conversationconversation_read
conversation_participant_removedParticipants were removed from a conversationconversation_read
button_clickedA button was clicked in a conversation. The payload will include the contact ID.conversation_read
playbook_goal_metThis 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_unsubscribedA user unsubscribed from all emails - this is invoked whenever someone opts out of email communication (either manually, or by the API).user_read
new_meetingA 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_updatedA previously booked meeting was either rescheduled or canceled.conversation_read
contact_updatedA contact record has been updated in Driftall_contact_read
gdpr_delete_requestedA user requested a GDPR-deletion of a contact from drift privacy settings or the API.gdpr_read
app_disconnectedA Drift user (organization) disconnected your app.no scope required
user_availability_updatedA Drift user's availability has been changed.user_read
phone_capturedA phone number was captured in a conversationconversation_read
chat_to_callA Drift user completed call with Chat to Callconversation_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 

{
  "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. Be sure to select the toggle for "Use session timeout to sync data to your integrations" in order to enable this webhook. For each new message in 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', // or '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

Fires 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 fires 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 fires 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 fires whenever a Drift user's availability changes. You can test it 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 fires 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 fires when 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 12 days ago