Webhooks

Register a webhook endpoint

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.

post/v1/webhooks

Request

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

Request body

urlstring uri required

Public HTTPS URL to POST events to.

eventsstring[]

Events to deliver. Omit or [] = all events.

Response

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

webhook_idstring required
urlstring uri required
eventsstring[] required

[] = subscribed to all events.

activeboolean required
created_atstring date-time required
secretstring 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

Changes

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