Skip to main content
The Dmand AI API does not return enrichment results in the submit response. When you submit an enrichment, the API immediately returns a batch_id and a requests array. Results are delivered later by webhook or retrieved by polling. Webhooks are the recommended way to receive results because they do not count against your rate limit.

Why webhooks

Webhooks push results to your server as soon as they are ready. You do not need to poll or keep a connection open. They are faster than polling and do not consume your rate limit.

How it works

  1. Include a webhook object in your single or bulk submit request.
  2. Dmand processes the NPI and resolves or verifies the email.
  3. Dmand POSTs the result to your callback URL in the same envelope format used by polling.
  4. Your server verifies the X-LNZ-Signature header before processing the payload. See Verifying webhook signatures.

Webhook modes

Choose how you want to receive notifications with the webhook.mode field.
  • real-time (default): One webhook per NPI as it resolves. Use this when you want to act on each result immediately.
  • batch: One webhook when the entire batch completes. Use this when you only need the final summary.

Submit with a webhook

webhook.url must use https://. Submit requests with an http:// webhook URL are rejected with 422 Unprocessable Entity, and no enrichment is started.

Webhook payload

The payload uses the same envelope as polling and batch poll responses, plus a top-level event field that identifies the webhook type. The webhook object describes the delivery configuration, and data contains the per-NPI results.
If no webhook was provided, the webhook field is null.
The event field appears only in webhook payloads. Poll responses from Get Request and Get Batch do not include it. If you process webhooks and poll responses with shared code, do not require event to be present.

Echoing custom data with custom_data

Include custom_data in the submit body to attach any JSON object. It is echoed verbatim in every poll response and webhook payload. Use it to pass internal identifiers, correlation IDs, or tags so you can match results to your own records.

Responding to webhooks and retry behavior

Your endpoint must return an HTTP 2xx response as quickly as possible. Perform heavy processing in a background job so you do not block the response. If your endpoint returns a non-2xx response, Dmand retries delivery with backoff. Make your handler idempotent and deduplicate by request_id to avoid processing the same result more than once.

Verifying webhook signatures

Every webhook request from Dmand AI includes an X-LNZ-Signature header. Verify this signature before you trust or process a payload. It proves that the request came from Dmand AI and that the body was not changed in transit.

How the signature is generated

The signature is a hex-encoded HMAC-SHA256 digest of the exact raw request body, signed with your webhook secret:
  • Webhook secret: each API key has its own webhook secret. The Dmand AI team shares it with you once, when your API key is issued. Store it in a secret manager alongside your API key, and never expose it in client-side code.
  • Signed content: the signature covers the exact bytes of the JSON body that Dmand AI POSTs to your URL.
Compute the signature over the raw request body. Do not parse the JSON and re-serialize it first. Any change to whitespace, key order, or encoding produces a different digest and makes verification fail.

Verify the signature

When a webhook arrives:
  1. Read the raw request body as bytes.
  2. Compute the HMAC-SHA256 of the body using your webhook secret, and hex-encode the result.
  3. Compare your result to the X-LNZ-Signature header using a constant-time comparison.
  4. If the header is missing or the values do not match, reject the request with 401 and do not process it.
Always use a constant-time comparison such as hmac.compare_digest in Python or crypto.timingSafeEqual in Node.js. A regular string comparison (== or ===) can leak timing information that helps an attacker guess a valid signature.

What signature verification protects against

Limitations

  • Not encryption. The signature does not hide the payload. Confidentiality comes from HTTPS, which Dmand AI requires for every webhook URL.
  • No built-in replay protection. The signature does not include a timestamp or nonce, so a captured valid request could be re-sent. Protect against this by deduplicating on request_id and ignoring results you have already processed.

Troubleshooting failed verification

  • Signature never matches: make sure you hash the raw body bytes, not a parsed and re-serialized object. Frameworks that parse JSON automatically, such as express.json(), discard the original bytes.
  • Wrong secret: the webhook secret is tied to a specific API key. If you received a new API key, update your webhook secret to the one issued with it.
  • Lost secret: contact hello@dmand.ai to have your webhook secret reissued.

Testing webhooks

Use webhook.site to get a temporary URL and inspect real payloads without setting up your own server.

Polling fallback

If you cannot receive webhooks, you can poll GET /api/v1/email/{request_id} or GET /api/v1/batch/{batch_id}. Polling consumes your rate limit and delivers results more slowly. If you must poll, space requests at reasonable intervals. Do not rely solely on webhooks; poll as a fallback if a webhook does not arrive.