Not Receiving Any Webhook Notifications?
Webhooks don't activate automatically. You need to include the webhookUrl field in every enrichment request you want to be notified about.
What to do: Make sure your request body includes:
"notificationOptions": {
"webhookUrl": "https://your-server.com/webhook"
}
→ See: API - Webhooks
Your webhook URL is using HTTP instead of HTTPS
Surfe only accepts HTTPS webhook URLs. To help add to the security of webhook communication, usage of https endpoints is required.
What to do: Make sure your URL starts with https:// not http://.
Your server isn't publicly accessible
Surfe's servers need to be able to reach your webhook endpoint. If your server is running locally or behind a firewall, Surfe can't deliver the notification.
What to do: Make sure your endpoint is publicly accessible.
Your server isn't responding with 200 OK
If your server doesn't respond with a 200 OK, Surfe may retry the request. If it consistently fails, notifications may stop being delivered.
What to do: Make sure your endpoint responds with 200 OK as quickly as possible. Do any heavy processing after confirming receipt.
Receiving Notifications But the Data Looks Wrong
The payload structure is unexpected
The webhook payload structure is fixed — it always follows the same format for each event type. If the data looks unexpected, make sure you're parsing the correct fields.
What to do: Check the payload structure in the webhooks documentation and make sure your code is reading the right fields.
→ See: API - Webhooks
You're receiving duplicate notifications
If your server doesn't respond with 200 OK on the first delivery, Surfe may retry and your server could receive the same payload more than once.
What to do: Use the enrichmentID in the payload to deduplicate notifications on your side — if you've already processed that ID, ignore the duplicate.
Signature Verification Failing
Your shared secret is wrong
If your HMAC signature verification is failing, the most likely cause is that you're using the wrong shared secret.
What to do: Go to your API settings and confirm you're using the correct webhook shared secret key. Remember — the key only becomes available after you've received your first webhook notification.
The timestamp is outside your tolerance window
If signature verification is passing but you're rejecting requests, your tolerance window for the timestamp check may be too strict.
What to do: Make sure you're allowing a reasonable time window between the timestamp in the signature header and your current time.
You're verifying the wrong payload
The signature is computed against the raw JSON request body. If you parse the body before verifying, the signature will fail.
What to do: Always verify the signature against the raw unparsed request body.
Testing Your Webhook
For testing purposes only, you can use a tool like webhook.site, a free third party tool that gives you a temporary public URL to capture and inspect webhook payloads. Do not use this with real customer data.
Still Having Issues?
If you've worked through all of the above and webhooks still aren't working as expected, reach out to our support team via Intercom.