How do I receive webhooks and check their signature?

Add an endpoint

1. Open Developer → Webhooks and go to Add an endpoint.
2. Enter the Address: https, on a server reachable from the internet. Private, local and reserved addresses are refused when you save and again at every delivery. Redirects are not followed.
3. Tick the events you want: audit.completed, scan.failed, backlink.new, backlink.lost, order.placed, order.verified, gbp.review.new and lead.captured.
4. Press Add endpoint and copy the signing secret (whsec_…). It is shown once.
5. Press Send test event to receive a test.ping.

What arrives

A POST with a JSON body holding id, type, created_at, workspace_id and data, and these headers: SEOmise-Event, SEOmise-Delivery, SEOmise-Event-Id and SEOmise-Signature. Answer with any 2xx within 10 seconds. A redelivery keeps the same SEOmise-Event-Id, so use it to ignore duplicates.

Check the signature

The header looks like t=1791118800,v1=5f2c….

1. Split it on commas to get t (a Unix time) and v1.
2. Reject it if t is more than 5 minutes away from now. This stops replays.
3. Work out the HMAC-SHA256, as hex, of t, a full stop and the raw request body, using your signing secret.
4. Compare it with v1 using a constant-time comparison.

Always use the raw body exactly as received, before any JSON parsing. In PHP:

$ok = hash_equals(hash_hmac('sha256', $t.'.'.$rawBody, $secret), $v1);

Retries and switching off

• A failed delivery (not 2xx, a timeout or a refused address) is retried after 1, 2, 4, 8 and 16 minutes: 6 attempts in all.
• Deliveries shows each delivery's status, attempts, response code and the start of the response. Redeliver sends one again.
• After 15 failed attempts in a row the endpoint is switched off and the workspace owners get an e-mail. Fix your receiver, then press Switch on, which resets the count.
• New secret replaces the signing secret. Update your receiver straight away.
• Delivery logs are kept for 30 days.