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 and voice) are delivered as a unified agent.message event. The channel field tells you whether it came from SMS or a voice call:

Webhook payload

Each webhook delivery includes the following structure. Both SMS 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
    "direction": "inbound",
13
    "receivedAt": "2025-01-15T12:00:00Z"
14
  },
15
  "conversationState": {
16
    "customerName": "Jane Doe",
17
    "orderId": "ORD-12345"
18
  },
19
  "recentHistory": [
20
    { "content": "Hello", "direction": "inbound", "channel": "sms", "at": "2025-01-15T11:59:00Z" }
21
  ]
22
}

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
}

Voice webhook responses

For voice events, your webhook must return a response that tells the agent what to say. We strongly recommend streaming NDJSON for the lowest perceived latency:

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.

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

1
{
2
  "text": "How can I help you?",
3
  "voice": "Polly.Amy",
4
  "hangup": false
5
}

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
  "createdAt": "2025-01-15T11:00:00Z"
8
}

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" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

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

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
}