---
title: "Register a webhook endpoint. The signing secret is returned IN FULL exactly once. Every delivery is a POST with headers X-Seomatic-Event, X-Seomatic-Delivery, X-Seomatic-Timestamp (unix seconds) and X-Seomatic-Signature: `t=<timestamp>,v1=<hex>`, where v1 = HMAC-SHA256(secret, `<timestamp>.<raw body>`). During a secret rotation the header carries one v1 per active secret (`t=..,v1=<new>,v1=<old>`): accept the event if ANY v1 matches. Verify with a constant-time compare and reject timestamps older than a few minutes (replay). Respond 410 Gone to unsubscribe: the endpoint is removed."
method: POST
path: "/webhooks"
---

# Register a webhook endpoint. The signing secret is returned IN FULL exactly once. Every delivery is a POST with headers X-Seomatic-Event, X-Seomatic-Delivery, X-Seomatic-Timestamp (unix seconds) and X-Seomatic-Signature: \`t=<timestamp>,v1=<hex>\`, where v1 = HMAC-SHA256(secret, \`<timestamp>.<raw body>\`). During a secret rotation the header carries one v1 per active secret (\`t=..,v1=<new>,v1=<old>\`): accept the event if ANY v1 matches. Verify with a constant-time compare and reject timestamps older than a few minutes (replay). Respond 410 Gone to unsubscribe: the endpoint is removed.

`POST /webhooks`

## Request

- Base URL: `https://app.seomatic.ai/api/v1`
- URL: `https://app.seomatic.ai/api/v1/webhooks`
- Auth: HTTP bearer

## Request body

- object
  - `url` string, uri, required: https endpoint to receive signed POSTs.
  - `events` string[]: Subscribed events. Empty = all events.

## Response `201`

The endpoint + its full signing secret

## Other responses

- `400`: Invalid or non-public URL (SSRF-rejected)
- `401`: Missing or invalid API key
- `402`: Webhooks require the Infrastructure plan
- `409`: Per-workspace endpoint cap reached
- `429`: Rate limited (per key). Retry-After header set.

---

[API](https://skmtc.dev/seomatic/apis/seomatic-api.md) · [All operations](https://skmtc.dev/seomatic/apis/seomatic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/seomatic/apis/seomatic-api/revisions/113a2a263604?raw)