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
PINGHealth check/test webhookManual test
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",
    "startDate": "2024-01-15T10:30:00Z",
    "recordingUrl": "https://storage.withallo.com/recordings/abc123.mp3",
    "fromNumber": "+1234567890",
    "fromName": "John Doe",
    "to": "+0987654321",
    "toName": "Acme Support",
    "lengthInMinutes": 5.5,
    "length": "5m 30s",
    "tag": "support",
    "summary": "Customer called about order status and delivery timeline.",
    "oneSentenceSummary": "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."
      }
    ],
    "concatenatedTranscript": "AGENT: Hello, how can I help you today?\nUSER: Hi, I'm calling about my order status.",
    "dataCollected": {
      "orderNumber": "12345",
      "customerEmail": "[email protected]"
    },
    "type": "INBOUND",
    "integrationId": null,
    "transferFrom": null,
    "transferTo": {
      "number": "+1555123456",
      "userEmail": "[email protected]",
      "userName": "Support Team"
    }
  }
}
Field descriptions:
FieldTypeDescription
idstringUnique call identifier
startDatedatetimeWhen the call started
recordingUrlstring | nullURL to the call recording
fromNumberstringCaller’s phone number
fromNamestring | nullCaller’s name if known
tostringReceiving phone number
toNamestring | nullReceiver’s name if known
lengthInMinutesnumberCall duration in minutes
lengthstringHuman-readable duration (e.g., “2m 30s”)
tagstring | nullCategory tag assigned to the call
summarystring | nullAI-generated call summary
oneSentenceSummarystring | nullBrief one-sentence summary
transcriptionsarrayArray of transcript entries
concatenatedTranscriptstringFull transcript as plain text
dataCollectedobjectKey-value pairs of data collected during the call
typestringINBOUND or OUTBOUND
integrationIdstring | nullAssociated integration ID
transferFromobject | nullTransfer source details
transferToobject | nullTransfer destination details

​
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.",
    "sentAt": "2024-01-15T10:30:00Z",
    "fromNumber": "+1234567890",
    "toNumber": "+0987654321",
    "fromName": "John Doe",
    "toName": "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.",
    "sentAt": "2024-01-15T10:35:00Z",
    "fromNumber": "+0987654321",
    "toNumber": "+1234567890",
    "fromName": "Acme Support",
    "toName": "John Doe"
  }
}
SMS field descriptions:
FieldTypeDescription
idstringUnique message identifier
directionstringINBOUND or OUTBOUND
typestringSMS or MMS
contentstringMessage content
sentAtdatetimeWhen the message was sent/received
fromNumberstringSender’s phone number
toNumberstringRecipient’s phone number
fromNamestringSender’s name
toNamestringRecipient’s name

​
CONTACT_CREATED

Sent when a new contact is created. 
{
  "topic": "CONTACT_CREATED",
  "data": {
    "id": "cnt_abc123",
    "name": "John",
    "lastName": "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",
    "lastName": "Smith",
    "company": "Acme Inc",
    "emails": ["[email protected]", "[email protected]"],
    "numbers": ["+15551234567"]
  }
}
Contact field descriptions:
FieldTypeDescription
idstringContact PID
namestring | nullFirst name
lastNamestring | nullLast name
companystring | nullCompany name
emailsarrayList of email addresses
numbersarrayList of phone numbers