Webhooks

Webhooks are the fastest way to react to SurfacedBy events in your own systems. Instead of polling the API for new scans or alerts, you register an HTTPS endpoint, and SurfacedBy POSTs a signed JSON payload to it as soon as the event occurs. Webhooks are available on Professional and Business plans.

When to use webhooks

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

• Post a Slack message when a scan completes.
• Open a ticket in your PM tool when Visibility Score Dropped fires.
• Refresh a cached analytics dashboard when a scan completes.
• Kick off a downstream content audit when citation.changed fires.

What you get out of the box

• Eight event types covering scans, alerts, citations, domains, competitors, and reports.
• HMAC-SHA256 request signing so you can verify the payload really came from SurfacedBy.
• At-least-once delivery with exponential backoff retries.
• A dead-letter queue for deliveries that keep failing, so you can investigate without losing data.

What is covered in detail

• Overview - delivery guarantees, retries, dead-letter behaviour.
• Events - the full list of event types and their payloads.
• Signatures - HMAC-SHA256 verification with code samples in Python, Node, and PHP.