Webhooks

Notify Fin of Conversation Events

Request

This endpoint handles two distinct use cases depending on whether an event_type is provided:

1. Conversation Synchronization (default behavior)

When you omit the event_type field, Fin will synchronize the conversation by pulling the latest data from your endpoints. Use this when:

An agent sends a message
The conversation state changes (status, assignee, etc.)
Any other conversation data changes that Fin should know about

Example payload:

{
  "conversation_id": "conv_456"
}

2. Agent Typing Indicator

When you set event_type to agent_typing, Fin will display a typing indicator to the end-user in the Fin Messenger. No synchronization occurs - this is purely a real-time UI update.

Use this when an agent starts typing a response in your helpdesk. The typing indicator automatically dismisses after a few seconds.

Important: When using event_type: "agent_typing", the data.agent field is required and must include the agent's id, user_type, name, and email.

Example payload:

{
  "conversation_id": "conv_456",
  "event_type": "agent_typing",
  "data": {
    "agent": {
      "id": "agent_001",
      "user_type": "agent",
      "name": "Sarah Johnson",
      "email": "sarah.johnson@company.com"
    }
  }
}

Security

WebhookSignature

Path

integration_idstringrequired

The ID of your integration. You can find this in the Fin Deployment UI.

Example:a3c729d4e8f6b15c

Bodyapplication/jsonrequired

conversation_idstringrequired

ID of the conversation in your system

Example:"conv_456"

event_typestring

Optional. The type of event that occurred.

Omitted or null: Fin will synchronize the conversation by pulling the latest data from your endpoints.
agent_typing: Displays a typing indicator to the end-user. No synchronization occurs. Requires data.agent to be provided.

Value:"agent_typing"

dataobject

Additional event data. Required fields depend on the event_type:

For agent_typing: the agent field is required.

curl -i -X POST \
  https://api.intercom.io/hooks/standalone/custom_helpdesk_conversation_event/a3c729d4e8f6b15c \
  -H 'Content-Type: application/json' \
  -H 'X-Webhook-Key: YOUR_API_KEY_HERE' \
  -d '{
    "conversation_id": "conv_456"
  }'

Responses

Webhook accepted