Configuring webhooks - Allo

Webhooks allow you to receive real-time notifications when events occur in your Allo account.

Available Topics

Subscribe to the following webhook topics:

Topic	Description	Trigger
`CALL_RECEIVED`	Triggered when a call is completed	After call ends
`SMS_RECEIVED`	Triggered when an SMS is sent or received	After SMS sent or received
`CONTACT_CREATED`	Triggered when a contact is created	After contact creation
`CONTACT_UPDATED`	Triggered when a contact is updated	After contact update

Setting Up a Webhook

Use the Create Webhook endpoint to configure your webhook:

curl -X POST "https://api.withallo.com/v1/api/webhooks" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allo_number": "+1234567890",
    "enabled": true,
    "url": "https://your-server.com/webhook",
    "topics": ["CALL_RECEIVED", "SMS_RECEIVED", "CONTACT_CREATED"]
  }'

Webhook Requirements

Your webhook URL must be publicly accessible
Your server should respond with a 200 status code within 30 seconds
Use HTTPS for secure communication

Payload Format

All webhooks use a standard envelope format:

{
  "topic": "CALL_RECEIVED",
  "data": { /* topic-specific payload */ }
}

Webhook Payloads

CALL_RECEIVED

Sent when a call is completed.

{
  "topic": "CALL_RECEIVED",
  "data": {
    "id": "call_abc123",
    "start_date": "2024-01-15T10:30:00Z",
    "recording_url": "https://storage.withallo.com/recordings/abc123.mp3",
    "from_number": "+1234567890",
    "from_name": "John Doe",
    "to": "+0987654321",
    "to_name": "Acme Support",
    "length_in_minutes": 5.5,
    "length": "5m 30s",
    "tag": "support",
    "summary": "Customer called about order status and delivery timeline.",
    "one_sentence_summary": "Order status inquiry",
    "transcriptions": [
      {
        "source": "AGENT",
        "time": "2024-01-15T10:30:05Z",
        "text": "Hello, how can I help you today?"
      },
      {
        "source": "USER",
        "time": "2024-01-15T10:30:10Z",
        "text": "Hi, I'm calling about my order status."
      }
    ],
    "concatenated_transcript": "AGENT: Hello, how can I help you today?\nUSER: Hi, I'm calling about my order status.",
    "data_collected": {
      "orderNumber": "12345",
      "customerEmail": "[email protected]"
    },
    "ivr_result": [
      {
        "dtmf_key": "2",
        "text_key": "Sales"
      }
    ],
    "type": "INBOUND",
    "result": "ANSWERED",
    "integration_id": null,
    "transfer_from": {
      "number": "+1555000000",
      "user_email": "[email protected]",
      "user_name": "First Agent"
    },
    "transfer_to": {
      "number": "+1555123456",
      "user_email": "[email protected]",
      "user_name": "Support Team"
    },
    "transfer_original_call_id": "call_original123",
    "user_email": "[email protected]",
    "original_to_number": "+0987654321",
    "original_to_name": "Main Line"
  }
}

Field descriptions:

Field	Type	Description
`id`	string	Unique call identifier
`start_date`	datetime	When the call started
`recording_url`	string \| null	URL to the call recording
`from_number`	string	Caller’s phone number
`from_name`	string \| null	Caller’s name if known
`to`	string	Receiving phone number
`to_name`	string \| null	Receiver’s name if known
`length_in_minutes`	number	Call duration in minutes
`length`	string	Human-readable duration (e.g., “2m 30s”)
`tag`	string \| null	Category tag assigned to the call
`summary`	string \| null	AI-generated call summary
`one_sentence_summary`	string \| null	Brief one-sentence summary
`transcriptions`	array	Array of transcript entries
`concatenated_transcript`	string	Full transcript as plain text
`data_collected`	object	Key-value pairs of data collected during the call
`ivr_result`	array	IVR menu selections made during the call (see IVR result object below)
`type`	string	`INBOUND` or `OUTBOUND`
`result`	string	Call result status. One of: `ANSWERED`, `VOICEMAIL`, `TRANSFERRED_AI`, `TRANSFERRED_EXTERNAL`, `BLOCKED`, `FAILED`
`integration_id`	string \| null	Associated integration ID
`transfer_from`	object \| null	Transfer source details (see transfer object below)
`transfer_to`	object \| null	Transfer destination details (see transfer object below)
`user_email`	string	Email of the user/route owner
`original_to_number`	string \| null	Original number dialed (before routing)
`original_to_name`	string \| null	Original name for the dialed number
`transfer_original_call_id`	string \| null	Call ID of the first call in the transfer chain (same for all calls in the chain)

Transfer object fields (transfer_from / transfer_to):

Field	Type	Description
`number`	string \| null	Phone number of the transfer party
`user_email`	string \| null	Email of the user who transferred/received
`user_name`	string \| null	Name of the user who transferred/received

IVR result object fields (ivr_result):

Field	Type	Description
`dtmf_key`	string \| null	The DTMF digit pressed (e.g., “1”, “2”, “3”)
`text_key`	string	The IVR menu option label (e.g., “Sales”, “Support”)

SMS_RECEIVED

Sent when an SMS message is sent or received. Use the direction field to determine if the SMS is inbound or outbound.

{
  "topic": "SMS_RECEIVED",
  "data": {
    "id": "sms_abc123",
    "direction": "INBOUND",
    "type": "SMS",
    "content": "Hi, I'd like to schedule an appointment.",
    "sent_at": "2024-01-15T10:30:00Z",
    "from_number": "+1234567890",
    "to_number": "+0987654321",
    "from_name": "John Doe",
    "to_name": "Acme Support"
  }
}

SMS field descriptions:

Field	Type	Description
`id`	string	Unique message identifier
`direction`	string	`INBOUND` or `OUTBOUND`
`type`	string	`SMS` or `MMS`
`content`	string	Message content
`sent_at`	datetime	When the message was sent/received
`from_number`	string	Sender’s phone number
`to_number`	string	Recipient’s phone number
`from_name`	string	Sender’s name
`to_name`	string	Recipient’s name

CONTACT_CREATED

Sent when a new contact is created.

{
  "topic": "CONTACT_CREATED",
  "data": {
    "id": "cnt_abc123",
    "name": "John",
    "last_name": "Doe",
    "company": "Acme Inc",
    "emails": ["[email protected]"],
    "numbers": ["+15551234567"]
  }
}

CONTACT_UPDATED

Sent when an existing contact is updated.

{
  "topic": "CONTACT_UPDATED",
  "data": {
    "id": "cnt_abc123",
    "name": "John",
    "last_name": "Smith",
    "company": "Acme Inc",
    "emails": ["[email protected]", "[email protected]"],
    "numbers": ["+15551234567"]
  }
}

Contact field descriptions:

Field	Type	Description
`id`	string	Contact PID
`name`	string \| null	First name
`last_name`	string \| null	Last name
`company`	string \| null	Company name
`emails`	array	List of email addresses
`numbers`	array	List of phone numbers

Documentation Index

​Available Topics

​Setting Up a Webhook

​Webhook Requirements

​Payload Format

​Webhook Payloads

​CALL_RECEIVED

​SMS_RECEIVED

​CONTACT_CREATED

​CONTACT_UPDATED