---
title: "Register a webhook endpoint"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Register a webhook endpoint

`POST /v1/webhooks`

## Request

- Base URL: `https://serp-agent.com`
- URL: `https://serp-agent.com/v1/webhooks`
- Auth: HTTP bearer

Registers an HTTPS endpoint to receive event POSTs. `events` filters which events are delivered — omit it (or pass `[]`) to subscribe to ALL events. The response includes the raw signing `secret` exactly once (only an encrypted form is stored). URLs must be public HTTPS (private/internal hosts are refused). Max 20 endpoints per account. Deliveries retry with exponential backoff (up to 8 attempts, capped at 6h between attempts); an endpoint is auto-deactivated after 50 consecutive failures.

## Request body

- object
  - `url` string, uri, required: Public HTTPS URL to POST events to.
  - `events` string[]: Events to deliver. Omit or [] = all events.

## Response `201`

Endpoint registered. `secret` is shown exactly once — store it to verify signatures.

- WebhookCreated
  - `webhook_id` string, required
  - `url` string, uri, required
  - `events` string[], required: [] = subscribed to all events.
  - `active` boolean, required
  - `created_at` string, date-time, required
  - `secret` string, required: Raw signing secret (64 hex chars) — shown exactly once, never retrievable again.
  - `signature_header` 'X-SerpAgent-Signature', required
  - `signature_scheme` 'hex sha256 HMAC of the raw request body', required

## Other responses

- `400`: Invalid URL (must be public https), unknown event name, or malformed body. Code: `invalid_request`.
- `401`: Missing, malformed, unknown, revoked, or expired API key. Codes: `unauthorized`, `key_revoked`, `key_expired`.
- `409`: Endpoint cap reached (20 per account). Code: `limit_reached`.
- `429`: Rate limit exceeded (600 requests/minute per API key). Honor `Retry-After`.
- `500`: Server-side secret encryption unavailable. Code: `internal_error`.

---

[API](https://skmtc.dev/serp-agent/apis/serp-agent-api.md) · [All operations](https://skmtc.dev/serp-agent/apis/serp-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/serp-agent/apis/serp-agent-api/revisions/438a943019ac?raw)