Webhooks

Webhooks let your own systems react to SurfacedBy events without polling the API. You register an endpoint URL, and SurfacedBy POSTs a signed JSON payload to it when a subscribed event occurs. Dashboard webhooks need a paid plan (the trial included); a workspace owner or admin manages endpoints under Settings > Integrations > Webhooks. A workspace below a paid plan keeps its endpoints but receives no events until it is on a paid plan again. Webhooks registered in the Console are not limited by plan.

When to use webhooks

Webhooks fit any workflow that should run as soon as something changes:

• Post a message to your team chat when a check completes.
• Open a ticket when an alert.triggered event arrives with alert_type visibility_drop (Visibility Score Dropped).
• Refresh a cached analytics dashboard when a check completes.
• Start a content review when citation.changed reports a drop.

What you get

• Eight event types covering checks, alerts, citations, domains, competitors, and reports.
• HMAC-SHA256 request signing, so you can verify a payload came from SurfacedBy.
• At-least-once delivery with automatic retries over roughly eight and a half hours.
• A delivery log per endpoint with response details, a test-event button, and one-click replay.

Details

• Overview - registering endpoints, delivery, retries, the delivery log.
• Events - every event type and its payload.
• Signatures - HMAC-SHA256 verification with code samples in Python, Node.js, and PHP.