Outbound webhooks

An outbound webhook sends leadmaps activity to an HTTPS endpoint that you control. Use it for an internal service or for a tool that can receive webhooks. This is different from the inbound source webhooks described in the API reference.

Outbound webhooks completed production retry and duplicate-delivery verification and are supported on Hobby, Pro, and Business. They use one integration hub connection slot.

Create a connection

1. Create an HTTPS endpoint that accepts POST requests.
2. Open Settings, then Integrations, then Webhooks.
3. Enter a recognizable connection name and the endpoint URL.
4. Enter a strong signing secret between 32 and 128 printable ASCII characters.
5. Store the secret in your password manager or server secret store.
6. Save the connection and choose Send test.

leadmaps never displays the secret again. If it is lost or exposed, disconnect the destination and create it again with a new secret.

Delivery format

Each request has content-type: application/json and uses this versioned shape:

{
  "schema": "leadmaps.integration.delivery@1",
  "delivery_id": "019f84c2-c0b5-7d13-b5f8-99ac768f2aa4",
  "idempotency_key": "rule:lead:occurrence",
  "action": "send_notification",
  "subject": {
    "type": "lead",
    "ref": "019f84c2-c0b5-7d13-b5f8-99ac768f2aa5",
    "state": "open",
    "stage": "Qualified",
    "expected_value": "2500.00",
    "currency": "EUR"
  },
  "links": {
    "dashboard": "https://app.leadmaps.nl/leads"
  }
}

Fields can be absent when they do not apply. Ignore additional fields so your receiver remains compatible with future additive updates. Use schema to select the parser and delivery_id or idempotency_key to make your own side effect idempotent.

Verify the signature

Every delivery includes:

x-leadmaps-delivery-id: <delivery uuid>
x-leadmaps-timestamp: <unix seconds>
x-leadmaps-signature: v1=<lowercase sha256 hex>

Compute HMAC-SHA256 over the exact bytes of:

v1:<timestamp>:<raw request body>

Use your signing secret as the HMAC key, compare signatures in constant time, and reject a timestamp more than five minutes from your server clock. Verify the signature before parsing or acting on the body.

import { createHmac, timingSafeEqual } from 'node:crypto';

const signed = `v1:${timestamp}:${rawBody}`;
const expected = Buffer.from(
  createHmac('sha256', secret).update(signed, 'utf8').digest('hex'),
  'utf8',
);
const supplied = Buffer.from(signature.replace(/^v1=/, ''), 'utf8');
const valid = supplied.length === expected.length && timingSafeEqual(supplied, expected);

Read the raw body

Re-serializing parsed JSON can change whitespace or key order and make a valid signature fail. Keep the exact request body bytes until verification finishes.

Responses, retries, and duplicates

Return any 2xx status after accepting the delivery. Network failures, timeouts, rate limits, and 5xx responses are retried in the background. Permanent 4xx responses stop automatic retries and appear in delivery history for repair.

Retries can produce more than one request for the same logical action. Store the delivery_id or idempotency_key before performing your side effect and return success when you have already handled it.

Destination safety

Only HTTPS URLs are accepted. Credentials embedded in URLs, redirects, and private network destinations are refused. Disconnect and recreate a connection to rotate its URL or signing secret.