Webhooks

Webhooks deliver real-time notifications to your server when events occur in your AgentPhone project. Each project has a single master webhook endpoint that receives all events.

Events

All inbound messages (SMS, iMessage, and voice) are delivered as a unified agent.message event. The channel field tells you the source. When a call ends, agent.call_ended delivers the full transcript and call analysis. iMessage reactions trigger agent.reaction.

Webhook payload

Each webhook delivery includes the following structure. SMS, iMessage, and voice share the same top-level format:

1
{
2
  "event": "agent.message",
3
  "channel": "sms",
4
  "timestamp": "2025-01-15T12:00:00Z",
5
  "agentId": "agt_abc123",
6
  "data": {
7
    "conversationId": "conv_def456",
8
    "numberId": "num_xyz789",
9
    "from": "+15559876543",
10
    "to": "+15551234567",
11
    "message": "Hi, I need help with my order",
12
    "mediaUrl": null,
13
    "direction": "inbound",
14
    "receivedAt": "2025-01-15T12:00:00Z"
15
  },
16
  "conversationState": {
17
    "customerName": "Jane Doe",
18
    "orderId": "ORD-12345"
19
  },
20
  "recentHistory": [
21
    { "content": "Hello", "direction": "inbound", "channel": "sms", "at": "2025-01-15T11:59:00Z" }
22
  ]
23
}

agent.message fields by channel

agent.message keeps one envelope and changes only the data shape by channel:

For voice events, the data field contains the transcript instead:

1
{
2
  "event": "agent.message",
3
  "channel": "voice",
4
  "timestamp": "2025-01-15T14:00:05Z",
5
  "agentId": "agt_abc123",
6
  "data": {
7
    "callId": "call_abc123",
8
    "numberId": "num_xyz789",
9
    "from": "+15559876543",
10
    "to": "+15551234567",
11
    "status": "in-progress",
12
    "transcript": "I need help with my order",
13
    "confidence": 0.95,
14
    "direction": "inbound"
15
  },
16
  "conversationState": null,
17
  "recentHistory": [
18
    { "content": "Hello, how can I help?", "direction": "outbound", "channel": "voice", "at": "2025-01-15T14:00:00Z" }
19
  ]
20
}

When a call ends, agent.call_ended delivers the full transcript (not limited by contextLimit), call duration, and optional analysis:

1
{
2
  "event": "agent.call_ended",
3
  "channel": "voice",
4
  "timestamp": "2025-01-15T14:05:30Z",
5
  "agentId": "agt_abc123",
6
  "data": {
7
    "callId": "call_ghi012",
8
    "numberId": "num_xyz789",
9
    "from": "+15559876543",
10
    "to": "+15551234567",
11
    "direction": "inbound",
12
    "status": "completed",
13
    "startedAt": "2025-01-15T14:00:00Z",
14
    "endedAt": "2025-01-15T14:05:30Z",
15
    "durationSeconds": 330,
16
    "disconnectionReason": "agent_hangup",
17
    "transcript": [
18
      { "role": "agent", "content": "Hello! How can I help you today?" },
19
      { "role": "user", "content": "I need help with my order." },
20
      { "role": "agent", "content": "Sure! Could you provide your order number?" }
21
    ],
22
    "summary": "Customer called about an order inquiry. Agent helped locate the order.",
23
    "userSentiment": "Positive",
24
    "callSuccessful": true
25
  }
26
}

When someone reacts to an iMessage your agent sent, agent.reaction is delivered:

1
{
2
  "event": "agent.reaction",
3
  "channel": "imessage",
4
  "timestamp": "2025-01-15T12:01:00Z",
5
  "agentId": "agt_abc123",
6
  "data": {
7
    "conversationId": "conv_def456",
8
    "numberId": "num_xyz789",
9
    "reactionType": "love",
10
    "fromNumber": "+15559876543",
11
    "direction": "inbound",
12
    "messageId": "msg_001",
13
    "messageBody": "Hey! How can I help?",
14
    "messageMediaUrl": null,
15
    "createdAt": "2025-01-15T12:01:00Z"
16
  }
17
}

The reactionType is one of: love, like, dislike, laugh, emphasize, question.

Voice webhook responses

For voice events, your webhook must return a JSON object ({...}) that tells the agent what to say. Non-object responses (numbers, strings, arrays) are ignored and the caller hears silence.

Streaming response (recommended): Return Content-Type: application/x-ndjson with newline-delimited JSON chunks. TTS starts speaking on the first chunk while your server continues processing.

{"text": "Let me check that for you.", "interim": true}
{"text": "I found 3 results for your order."}

Mark interim chunks with "interim": true — the final chunk (without interim) closes the turn. Voice webhooks have a 30-second default timeout (configurable from 5–120 seconds per webhook) — always stream an interim chunk before doing slow work like LLM tool calls.

Simple response: Return a single JSON object for instant replies.

1
{ "text": "How can I help you?" }

Security

Each webhook delivery includes these headers:

The signature is computed over the timestamp + body: the signed string is {timestamp}.{raw_body}, hashed with HMAC-SHA256 using your webhook secret. Always verify the timestamp is within 5 minutes to prevent replay attacks.

Verification example (Node.js)

1
const crypto = require('crypto');
2
3
function verifyWebhook(rawBody, signature, timestamp, secret) {
4
  // Reject requests older than 5 minutes
5
  if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) return false;
6
  const signedString = timestamp + '.' + rawBody;
7
  const expected = crypto
8
    .createHmac('sha256', secret)
9
    .update(signedString)
10
    .digest('hex');
11
  return signature === `sha256=${expected}`;
12
}
13
14
// Usage in Express:
15
// const sig = req.headers['x-webhook-signature'];
16
// const ts = req.headers['x-webhook-timestamp'];
17
// verifyWebhook(req.body, sig, ts, WEBHOOK_SECRET);

Verification example (Python)

1
import hmac
2
import hashlib
3
import time
4
5
def verify_webhook(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
6
    # Reject requests older than 5 minutes to prevent replay attacks
7
    if abs(time.time() - int(timestamp)) > 300:
8
        return False
9
    signed_string = f"{timestamp}.".encode() + raw_body
10
    expected = hmac.new(
11
        secret.encode(), signed_string, hashlib.sha256
12
    ).hexdigest()
13
    return hmac.compare_digest(f"sha256={expected}", signature)
14
15
# Usage in Flask/FastAPI:
16
# signature = request.headers["X-Webhook-Signature"]
17
# timestamp = request.headers["X-Webhook-Timestamp"]
18
# verify_webhook(request.body, signature, timestamp, WEBHOOK_SECRET)

Retry behavior

If your webhook endpoint fails or doesn’t respond, we automatically retry delivery with exponential backoff:

Handling duplicate deliveries

Due to retries, your endpoint may receive the same webhook multiple times. Use the X-Webhook-ID header for idempotency:

1
processed_webhooks = set()  # in production, use Redis or a database
2
3
@app.route('/webhook', methods=['POST'])
4
def webhook():
5
    webhook_id = request.headers.get('X-Webhook-ID')
6
    if webhook_id in processed_webhooks:
7
        return 'OK', 200  # already processed
8
9
    # ... process the webhook ...
10
11
    processed_webhooks.add(webhook_id)
12
    return 'OK', 200

1
const processed = new Set(); // in production, use Redis or a database
2
3
app.post('/webhook', (req, res) => {
4
  const webhookId = req.headers['x-webhook-id'];
5
  if (processed.has(webhookId)) return res.status(200).send('OK');
6
7
  // ... process the webhook ...
8
9
  processed.add(webhookId);
10
  res.status(200).send('OK');
11
});

Conversation state

Store custom metadata on conversations to persist context across messages. This state is included in every webhook payload as conversationState.

$
curl -X PATCH "https://api.agentphone.to/v1/conversations/conv_abc123" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "metadata": {
>
      "customerName": "John Smith",
>
      "orderId": "ORD-12345",
>
      "topic": "shipping"
>
    }
>
  }'

This metadata appears in subsequent webhook payloads as conversationState, enabling your AI backend to maintain context across messages without managing state yourself.

Create or update webhook

Configure the webhook endpoint for your project. Each project can have one active master webhook. If a webhook already exists, it will be updated.

POST /v1/webhooks

Request body

Example

$
curl -X POST "https://api.agentphone.to/v1/webhooks" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"url": "https://your-server.com/webhook", "contextLimit": 10}'

1
{
2
  "id": "wh_mno678",
3
  "url": "https://your-server.com/webhook",
4
  "secret": "whsec_abc123...",
5
  "status": "active",
6
  "contextLimit": 10,
7
  "timeout": 30,
8
  "createdAt": "2025-01-15T11:00:00Z"
9
}

Get webhook

Get the current webhook configuration for your project. Returns null if no webhook is configured.

GET /v1/webhooks

Delete webhook

Remove the master webhook configuration. Events will no longer be delivered.

DELETE /v1/webhooks

Example

$
curl -X DELETE "https://api.agentphone.to/v1/webhooks" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook deliveries

View the delivery history for your master webhook to monitor delivery status and debug issues.

GET /v1/webhooks/deliveries

Query parameters

Example

$
curl -X GET "https://api.agentphone.to/v1/webhooks/deliveries?limit=10&offset=0" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

1
{
2
  "items": [
3
    {
4
      "id": "del_pqr901",
5
      "messageId": "msg_001",
6
      "eventType": "agent.message",
7
      "status": "success",
8
      "httpStatus": 200,
9
      "errorMessage": null,
10
      "attemptCount": 1,
11
      "lastAttemptAt": "2025-01-15T12:00:01Z",
12
      "nextRetryAt": null,
13
      "createdAt": "2025-01-15T12:00:01Z"
14
    }
15
  ],
16
  "total": 124,
17
  "offset": 0,
18
  "limit": 10
19
}

Test webhook

Send a test webhook to verify your endpoint is working correctly. This sends a fake message payload to your configured URL.

POST /v1/webhooks/test

Example

$
curl -X POST "https://api.agentphone.to/v1/webhooks/test" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

1
{
2
  "success": true,
3
  "httpStatus": 200,
4
  "errorMessage": null
5
}