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

​
Available Topics

Subscribe to the following webhook topics:
TopicDescriptionTrigger
CALL_RECEIVEDTriggered when a call is completedAfter call ends
SMS_RECEIVEDTriggered when an SMS is receivedAfter SMS received
SMS_SENTTriggered when an SMS is sentAfter SMS sent
CONTACT_CREATEDTriggered when a contact is createdAfter contact creation
CONTACT_UPDATEDTriggered when a contact is updatedAfter 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]"
    },
    "type": "INBOUND",
    "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:
FieldTypeDescription
idstringUnique call identifier
start_datedatetimeWhen the call started
recording_urlstring | nullURL to the call recording
from_numberstringCaller’s phone number
from_namestring | nullCaller’s name if known
tostringReceiving phone number
to_namestring | nullReceiver’s name if known
length_in_minutesnumberCall duration in minutes
lengthstringHuman-readable duration (e.g., “2m 30s”)
tagstring | nullCategory tag assigned to the call
summarystring | nullAI-generated call summary
one_sentence_summarystring | nullBrief one-sentence summary
transcriptionsarrayArray of transcript entries
concatenated_transcriptstringFull transcript as plain text
data_collectedobjectKey-value pairs of data collected during the call
typestringINBOUND or OUTBOUND
integration_idstring | nullAssociated integration ID
transfer_fromobject | nullTransfer source details (see transfer object below)
transfer_toobject | nullTransfer destination details (see transfer object below)
user_emailstringEmail of the user/route owner
original_to_numberstring | nullOriginal number dialed (before routing)
original_to_namestring | nullOriginal name for the dialed number
transfer_original_call_idstring | nullCall ID of the first call in the transfer chain (same for all calls in the chain)
Transfer object fields (transfer_from / transfer_to):
FieldTypeDescription
numberstring | nullPhone number of the transfer party
user_emailstring | nullEmail of the user who transferred/received
user_namestring | nullName of the user who transferred/received

​
SMS_RECEIVED

Sent when an SMS message is received. 
{
  "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_SENT

Sent when an SMS message is sent. 
{
  "topic": "SMS_SENT",
  "data": {
    "id": "sms_xyz789",
    "direction": "OUTBOUND",
    "type": "SMS",
    "content": "Your appointment is confirmed for tomorrow at 2pm.",
    "sent_at": "2024-01-15T10:35:00Z",
    "from_number": "+0987654321",
    "to_number": "+1234567890",
    "from_name": "Acme Support",
    "to_name": "John Doe"
  }
}
SMS field descriptions:
FieldTypeDescription
idstringUnique message identifier
directionstringINBOUND or OUTBOUND
typestringSMS or MMS
contentstringMessage content
sent_atdatetimeWhen the message was sent/received
from_numberstringSender’s phone number
to_numberstringRecipient’s phone number
from_namestringSender’s name
to_namestringRecipient’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:
FieldTypeDescription
idstringContact PID
namestring | nullFirst name
last_namestring | nullLast name
companystring | nullCompany name
emailsarrayList of email addresses
numbersarrayList of phone numbers