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
- Include a
webhookobject in your single or bulk submit request. - Dmand processes the NPI and resolves or verifies the email.
- Dmand POSTs the result to your callback URL in the same envelope format used by polling.
- Your server verifies the
X-LNZ-Signatureheader before processing the payload. See Verifying webhook signatures.
Webhook modes
Choose how you want to receive notifications with thewebhook.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 payload
The payload uses the same envelope as polling and batch poll responses, plus a top-levelevent field that identifies the webhook type. The webhook object describes the delivery configuration, and data contains the per-NPI results.
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
Includecustom_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 byrequest_id to avoid processing the same result more than once.
Verifying webhook signatures
Every webhook request from Dmand AI includes anX-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.
Verify the signature
When a webhook arrives:- Read the raw request body as bytes.
- Compute the HMAC-SHA256 of the body using your webhook secret, and hex-encode the result.
- Compare your result to the
X-LNZ-Signatureheader using a constant-time comparison. - If the header is missing or the values do not match, reject the request with
401and do not process it.
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_idand 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.aito 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 pollGET /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.