---
title: "Set Webhook"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Set Webhook

`POST /v1/webhooks`

## Request

- Base URL: `https://api.agentline.cloud`
- URL: `https://api.agentline.cloud/v1/webhooks`
- Auth: HTTP bearer

Create or replace an agent's webhook.

The configured URL receives ALL of that agent's event types — call lifecycle
(`call.received`, `call.completed`, `call.failed`), SMS (`sms.received`),
and future events — as signed JSON POSTs. Each agent may have at most one
webhook; setting it again replaces the URL. Omitted secret,
signature_header, protocol and capabilities keep their current values.

Returns agent_id, url, the full secret (shown only here; get_webhook
masks it), signature_header, protocol, capabilities and created_at.
Store the secret to verify the signature header on deliveries.

## Request body

- WebhookConfig
  - `url` string, uri, required: HTTPS URL that will receive this agent's events as signed JSON POSTs. Setting this replaces any existing webhook for the agent.
  - `agent_id` string, required: ID (agt_...) of the agent whose events this webhook receives, from create_agent or list_agents. Each agent may have at most one webhook.
  - `secret` string, nullable: Optional HMAC signing secret used to verify the signature header on delivered payloads. Omit to keep the current secret, or to auto-generate one for a new webhook.
  - `signature_header` string, nullable: Header name for the HMAC-SHA256 signature of the raw body. Defaults to 'X-Webhook-Signature' (natively verified by Hermes, OpenClaw, and other agent platforms). Set to 'X-Hub-Signature-256' for GitHub-style verification, or any custom header name your platform expects. Omit to keep the existing value when updating.
  - `protocol` 'agentline-relay/1' | 'agentline-relay/2', nullable: Live relay protocol. 'agentline-relay/1' (default): one call.utterance POST per task, answer in the response body or via push. 'agentline-relay/2': typed POSTs (call.session.start, call.task.open, call.task.amend, call.task.cancel, call.session.end); answer only via POST /v1/calls/{call_id}/context and return 202 quickly. Omit to keep the existing value when updating.
  - `capabilities` WebhookCapabilities: What a webhook runtime supports on live relay calls (protocol v2).
    - `supports_amend` boolean: Accepts call.task.amend POSTs: caller follow-ups on the open task, same turn_id, higher revision. When false, AgentLine holds follow-ups and sends them as one merged task after the current one settles.
    - `supports_cancel` boolean: Accepts call.task.cancel POSTs when the caller withdraws a task.
    - `briefing` boolean: Accepts call.session.start at call start and pushes facts the caller is likely to need (disposition=facts, no turn_id).
    - `streams_progress` boolean: Pushes partial/progress updates while it works.

## Response `200`

Successful Response

- WebhookCreated: Returned on POST — exposes the full secret this one time.
  - `agent_id` string, required: Agent this webhook is scoped to
  - `url` string, required: Configured webhook URL
  - `secret` string, required: Full signing secret. Save it now — it is masked on subsequent reads.
  - `signature_header` string, required: Header name used for HMAC-SHA256 signature delivery.
  - `protocol` string: Live relay protocol.
  - `capabilities` object: Declared relay v2 capabilities.
  - `created_at` string, date-time, nullable: When the webhook was last (re)configured

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents.md) · [All operations](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents/llms.txt) · [OpenAPI document](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents/revisions/18c0bdbb4b30?raw)