Webhooks

Set Webhook

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.

post/v1/webhooks

Request

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

Request body

urlstring 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_idstring 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.

secretstring 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_headerstring 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.

Response

Successful Response

agent_idstring required

Agent this webhook is scoped to

urlstring required

Configured webhook URL

secretstring required

Full signing secret. Save it now — it is masked on subsequent reads.

signature_headerstring required

Header name used for HMAC-SHA256 signature delivery.

protocolstring

Live relay protocol.

capabilitiesobject

Declared relay v2 capabilities.

created_atstring date-time nullable

When the webhook was last (re)configured

Changes

No recorded changes to this operation across all 1 revision of this API.