Guides

Agent Webhooks

In addition to the project-level default webhook, you can configure individual webhook endpoints for each agent. When a per-agent webhook is set, it overrides the project default for that agent’s events — the event is delivered to exactly one endpoint, never both.

This is useful when you have multiple agents and want to route their events to different backend services or processing pipelines.

How it works

When an event occurs (e.g., an inbound message to an agent’s number):

  1. If the agent has its own webhook configured, the event is delivered only to the agent’s webhook
  2. If the agent does not have its own webhook, the event is delivered to the project default webhook

Events are never duplicated across both endpoints. Per-agent webhooks use the same payload format and signature verification mechanism described in the Webhooks guide.

Create or update agent webhook

Register or update a webhook URL for a specific agent.

POST /v1/agents/{agent_id}/webhook

Request body

FieldTypeRequiredDescription
urlstringYesThe HTTPS URL to receive webhook deliveries
contextLimitinteger or nullNoNumber of recent messages to include in webhook payloads (0-50, default: 10). Set to 0 to disable history.

A new signing secret is generated each time you create or update a webhook. Save the secret value from the response.

Example

$curl -X POST "https://api.agentphone.to/v1/agents/agt_abc123/webhook" \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"url": "https://your-server.com/agent-webhook", "contextLimit": 5}'
1{
2  "id": "wh_xyz789",
3  "url": "https://your-server.com/agent-webhook",
4  "secret": "whsec_def456...",
5  "status": "active",
6  "contextLimit": 5,
7  "createdAt": "2025-01-15T11:00:00Z"
8}

Get agent webhook

Get the webhook configuration for a specific agent. Returns null if no webhook is configured.

GET /v1/agents/{agent_id}/webhook

Example

$curl -X GET "https://api.agentphone.to/v1/agents/agt_abc123/webhook" \
>  -H "Authorization: Bearer YOUR_API_KEY"

Delete agent webhook

Remove the webhook for a specific agent. Events will revert to being delivered to the project default webhook after deletion.

DELETE /v1/agents/{agent_id}/webhook

Example

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

Agent webhook deliveries

View recent delivery attempts for a specific agent’s webhook.

GET /v1/agents/{agent_id}/webhook/deliveries

Query parameters

ParameterTypeRequiredDefaultDescription
limitintegerNo50Number of results to return (max 100)

Example

$curl -X GET "https://api.agentphone.to/v1/agents/agt_abc123/webhook/deliveries?limit=10" \
>  -H "Authorization: Bearer YOUR_API_KEY"
1[
2  {
3    "id": "del_abc123",
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 agent webhook

Send a test webhook to verify the agent’s webhook endpoint is working correctly.

POST /v1/agents/{agent_id}/webhook/test

Example

$curl -X POST "https://api.agentphone.to/v1/agents/agt_abc123/webhook/test" \
>  -H "Authorization: Bearer YOUR_API_KEY"
1{
2  "success": true,
3  "httpStatus": 200,
4  "errorMessage": null
5}