Webhooks
POST to your webhook endpoint when a submission or document changes. Configure your endpoint URL, event subscriptions, and signing secret in the Niva dashboard under Settings › Webhooks.mx), Brazil (br), Chile (cl), and Colombia (co).Webhook events
submission.created: A submission is created.submission.status_updated: Processing starts, or the status enters needs_review, pending_rfi, approved, or rejected.document.created: A document is uploaded through the API, or a new merged corporate document is created. Ordinary widget uploads do not send this event.document.validated: Instant document validation finishes. Read validation_status for the result; it can report a failed check.document.deleted: A document is removed through the API or archived by Niva, including some failed uploads.document.created contains the shape returned by Upload document; document.validated and document.deleted contain the shape returned by Get document.submission.status_updated and inspect payload.status. A processing event means processing started. A later needs_review, pending_rfi, approved, or rejected status tells you the next action to take. Use Get submission to retrieve the current full result.Message body
id, event, timestamp, and payload. id is Niva's message ID (whm_…), and timestamp is its creation time in UTC. The message ID stays the same when that message is retried.{
"id": "whm_2b9XkQe7Lm",
"event": "submission.status_updated",
"timestamp": "2026-10-23T21:31:33Z",
"payload": {
"id": "sub_12345AbCdE",
"token": "SUBMISSION_TOKEN",
"country_code": "mx",
"status": "needs_review",
"business_type": "persona_moral",
"legal_name": "Nueva Vista Alimentos S.A. de C.V.",
"tax_id_number": "NVA120409XD2",
"tax_id_label": "rfc",
"created_at": "2026-10-23T21:31:32Z",
"updated_at": "2026-10-23T21:31:33Z",
"external_id": "nueva-vista-001",
"policy_id": "pol_7mN2pQ8rXc4v",
"dashboard_url": "https://app.niva.co/dashboard/submissions/sub_12345AbCdE/details"
}
}Verify signatures
webhook-* and svix-* signature headers; pass the received headers through to the library. See Svix signature verification for supported languages and frameworks.svix, then verify the incoming request in your handler:Acknowledge and retry safely
2xx response promptly after you have safely accepted the message. Process longer work asynchronously. Non-2xx responses, redirects, and timeouts cause delivery failures and retries. Svix uses a backoff schedule; consult Svix's retry documentation and the delivery attempts shown in Settings › Webhooks.id to ignore duplicate deliveries. Different messages can describe the same submission status, so your processing should also tolerate repeated state notifications. Fetch the current submission when you need its latest state rather than assuming webhook arrival order.