Skip to main content
Webhooks enable your application to receive real-time event notifications from the Dataspike platform.
Instead of polling the API, you can register an endpoint that automatically receives updates for verification results, AML matches, and other key events.
⚡ Use case: Webhooks are essential for production integrations — they allow your systems to react immediately when verifications complete, AML matches occur, or applicants change status.

​
1. Understanding Webhooks

A webhook is an HTTP POST request sent by Dataspike to your configured endpoint whenever a specific event occurs. Example flow:
  1. You register a webhook URL (e.g. https://api.yourdomain.com/dataspike/webhook).
  2. A verification completes on Dataspike.
  3. Dataspike sends a signed POST request to your URL with the verification data.
Webhook payloads are sent as JSON objects and contain the event type, timestamp, and relevant entity data. Example payload: 
{
  "id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
  "webhook_id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11",
  "event_type": "AML_SCREENING",
  "timestamp": "2023-07-18T15:32:13Z",
  "payload": {}
}

​
2. Registering Webhook URLs

You can manage webhooks from your Dashboard → API → Webhooks tab. There, you can:
  • Add one or more webhook endpoints.
  • Assign events (e.g. AML_SCREENING and etc.).
  • Test and validate your configuration before going live.
Each webhook URL can be specific to an environment:
EnvironmentBase URLDescription
Sandboxhttps://sandboxapi.dataspike.ioFor integration testing with simulated data.
Productionhttps://api.dataspike.ioFor live verification and AML events.
After saving, click “Send Test” to verify your endpoint works correctly — a dummy event will be sent immediately.
💡 You can register multiple webhooks for different services (e.g. one for AML alerts, one for verifications).

​
3. Verifying Webhook Signatures

Dataspike signs every webhook request with HMAC-SHA256 so you can verify it genuinely came from us and the payload has not been tampered with.

​
Signature header

Each request includes:
HeaderDescription
X-Webhook-SignatureSignature in the format t={unix_timestamp},v1={hex_digest}
X-Webhook-Signature: t=1720018333,v1=a3f4b2c1d5e6...
  • t — Unix timestamp (seconds, UTC) of when the request was signed
  • v1 — HMAC-SHA256 digest of the signed payload, hex-encoded

​
How the signature is computed

Signed payload: "{t}.{raw_request_body}"
Concatenate the timestamp string, a literal ., then the raw JSON body bytes exactly as received — do not re-serialize or pretty-print. Key: hex-decode the secret after stripping the whsec_ prefix.

​
Your signing secret

When you create a webhook, the API response includes hmac_signing_secret: 
{
  "id": "01927ed4-c928-7a3c-9a30-7ab7cc169d11",
  "hmac_signing_secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
}
The signing secret is shown only once at creation time. Store it immediately in a secrets manager or environment variable — it cannot be retrieved again.
To replace the secret, call the rotate endpoint: 
POST /api/v3/organization/webhooks/{webhook_id}/hmac/rotate
The response contains a new hmac_signing_secret. Update your application with the new value before discarding the old one to avoid dropping events.

​
Verification examples

import crypto from "crypto";

// Use express.raw({ type: "application/json" }) to preserve the raw body bytes
function verifySignature(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "hex");
  const payload = Buffer.concat([Buffer.from(`${parts.t}.`), rawBody]);
  const expected = crypto.createHmac("sha256", key).update(payload).digest("hex");
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))) {
    throw new Error("Invalid signature");
  }
}

​
4. Handling Webhook Events

Your endpoint should:
  • Accept HTTP POST requests with a Content-Type: application/json header.
  • Parse the incoming payload.
  • Validate the event type and handle it accordingly.
  • Respond with HTTP 200 OK to acknowledge receipt.
Example Node.js handler: 
import express from "express";
const app = express();
app.use(express.json());

app.post("/dataspike/webhook", (req, res) => {
  const event = req.body;
  console.log("Received Dataspike event:", event.event);

  if (event.event === "DOCVER_EVENT") {
    // Handle verification result
  } else if (event.event === "AML_SCREENING") {
    // Handle AML hit
  }

  res.sendStatus(200);
});

app.listen(3000, () => console.log("Listening for webhooks on port 3000"));

​
5. Accessing Webhook History

Dataspike keeps a complete history of all webhook deliveries. From the Dashboard → API → Webhooks section, you can:
  • View successful and failed webhook attempts.
  • Inspect delivery payloads and response codes.
  • Replay failed deliveries manually.
This gives you full visibility and control over event delivery reliability.

​
6. Testing and Troubleshooting

Before going live:
  1. Test your webhook endpoint in the Sandbox environment.
  2. Use the “Send Test” button in the dashboard to ensure it works.
  3. Check logs in your app for failed requests or response timeouts.
  4. Confirm you return an HTTP 200 within a few seconds of receipt.
If events are not delivered:
  • Verify your server accepts HTTPS POST requests.
  • Ensure your endpoint is reachable from public networks.
  • Review Dashboard → API → Webhooks → History for error details.

​
Summary

Once configured, webhooks let you:
  • Receive instant updates on verification, AML, and KYT events.
  • Automate user state updates or trigger downstream processes.
  • Monitor and replay webhook events from the dashboard.

​
Next steps