Overview

Webhooks are HTTP POST requests that Urtentic sends to your server when something happens to a verification: it starts, the person submits their inputs, a check finishes, or the verification reaches its final status. Your server receives the event as soon as it happens instead of polling the API. To set up the URL and secret Urtentic uses, see Configuration.

How webhooks work

Something happens to a verification

For example, a check finishes or the verification reaches its final status.

Urtentic signs the event

The JSON payload is signed with your webhook secret (HMAC-SHA256).

Urtentic sends it to your URL

One POST request goes to the webhook URL of the verification’s workflow, or to your organization’s default URL.

Your server verifies and handles it

Check the signature, process the event, and respond with a 2xx status.

Events

Every event is sent. You can’t choose a subset, so ignore the ones you don’t need.

Event	Sent when
`verification_started`	A verification is created with `POST /verifications`
`verification_inputs_completed`	The person’s inputs are submitted
`step_completed`	One step of a verification process finishes, for example document verification or a phone check
`verification_completed`	The verification reaches its final status
`verification_data_updated`	Someone corrects the verification’s extracted data in the dashboard
`verification_abandoned`	The person’s inputs weren’t submitted within 24 hours of the verification being created. The verification is then deleted.

Payloads

Every event has these fields:

Field	Type	Description
`eventName`	string	One of the events above
`flowId`	string	ID of the verification’s workflow
`timeStamp`	string	When the event happened, ISO 8601 with offset, for example `2026-10-02T14:06:40.000+00:00`
`resource`	string	URL of the verification. The verification ID is the last path segment.
`metadata`	object	The `metadata` you passed when starting the verification, echoed back unchanged

verification_completed
step_completed
Other events

{
  "eventName": "verification_completed",
  "flowId": "db50ed08-18fa-41e8-9e46-a44aca39f69d",
  "timeStamp": "2026-10-02T15:30:00.000+00:00",
  "resource": "https://api.urtentic.com/api/v1/verifications/85c94e71-6e3f-4a19-b15c-781d8a876542",
  "metadata": {
    "userId": "user_12345",
    "reference": "REF-67890"
  },
  "verificationStatus": "SUCCESS"
}

verificationStatus is SUCCESS, REJECTED or NEEDS_REVIEW. verification_data_updated has the same shape.

{
  "eventName": "step_completed",
  "flowId": "db50ed08-18fa-41e8-9e46-a44aca39f69d",
  "timeStamp": "2026-10-02T15:25:00.000+00:00",
  "resource": "https://api.urtentic.com/api/v1/verifications/85c94e71-6e3f-4a19-b15c-781d8a876542",
  "metadata": { "userId": "user_12345" },
  "id": "phone-owner-validation",
  "status": 200,
  "data": {
    "phone_number": "+2348012345678",
    "status": "CONFIRMED"
  },
  "step": {
    "stepId": "phone-owner-validation",
    "status": 200,
    "data": {
      "phone_number": "+2348012345678",
      "status": "CONFIRMED"
    },
    "error": null,
    "startedAt": "2026-10-02T15:24:58.112",
    "completedAt": "2026-10-02T15:24:58.431"
  }
}

Field	Description
`id`	The step that finished
`status`	The step’s status code. `200` when the step ran normally.
`data`	What the step found. The shape depends on the step.
`step`	The full step, including `error` (with `severity`, `errorType` and `message`) and its start and end times

verification_started and verification_inputs_completed carry only the common fields:

{
  "eventName": "verification_started",
  "flowId": "db50ed08-18fa-41e8-9e46-a44aca39f69d",
  "timeStamp": "2026-10-02T14:00:00.000+00:00",
  "resource": "https://api.urtentic.com/api/v1/verifications/85c94e71-6e3f-4a19-b15c-781d8a876542",
  "metadata": { "userId": "user_12345", "reference": "REF-67890" }
}

verification_abandoned adds "verificationStatus": "ABANDONED".

metadata is yours to define. Put your own user ID or reference in it when you start the verification, and use it to match events to your records.

Signatures

Every request carries two headers:

POST /webhooks/urtentic HTTP/1.1
Content-Type: application/json
x-urtentic-signature: 9f2c4b0e6d1a8e3f5c7b2a4d6e8f0a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f
x-urtentic-timestamp: 1790950000

x-urtentic-signature is the hex HMAC-SHA256 of the raw request body. The key is your webhook secret, Base64-decoded.
x-urtentic-timestamp is when the request was sent, in Unix seconds. It is not part of the signature.

Compute the signature over the raw body bytes, before parsing the JSON. Re-serializing the parsed JSON can change the bytes and break the match. See Configuration for examples in several languages.

Delivery and retries

Your server has 30 seconds to respond to each request. A 2xx response means the event was delivered. If delivery fails, Urtentic tries again, up to 5 attempts in total:

Attempt	Sent
1	When the event happens
2	5 seconds after attempt 1 failed
3	10 seconds after attempt 2 failed
4	20 seconds after attempt 3 failed
5	40 seconds after attempt 4 failed

All attempts happen within 10 minutes of the event. After the last failed attempt, the event is dropped. Whether a failure is retried depends on what went wrong:

Your server’s response	Retried
`5xx`, or no response within 30 seconds	Yes
`429 Too Many Requests`	Yes
Connection refused, DNS failure or TLS error	Yes
Any other `4xx`, for example `400`, `401`, `404`	No, the event is dropped straight away

Respond with a 4xx only when you never want that event again. If your server is temporarily unable to process events, respond with 503 or 429 so they’re retried. Every attempt carries the same body and the same x-urtentic-signature. Only x-urtentic-timestamp changes.

Events are sent independently, so they can arrive out of order. A step_completed event can arrive after verification_completed.
A retry can deliver an event your server already processed, for example when it handled the request but responded after the 30-second timeout.
If neither the workflow nor your organization has a webhook URL, no events are sent.

An event can still be dropped, after a rejected 4xx or after all 5 attempts failed, so don’t rely on webhooks alone for anything you can’t afford to miss. If you haven’t received verification_completed when you expect it, check the verification with the status endpoint, GET /verifications/{verificationId}/status.

Best practices

Verify the signature on every request before trusting it.
Respond quickly. Return 2xx as soon as you’ve stored the event, and do slow work afterwards. A response after 30 seconds counts as a failure and the event is sent again.
Make handling idempotent. Retries can deliver the same event twice, and events have no ID of their own, so deduplicate on eventName plus the verification ID from resource (plus id for step_completed).
Use the right status code. 4xx stops retries for that event. Use 5xx or 429 when you want it sent again.
Use HTTPS. The dashboard only accepts https:// webhook URLs.

Getting Started

Verification Processes

Webhooks

SDK

How webhooks work

Events

Payloads

Signatures

Delivery and retries

Best practices

​How webhooks work

​Events

​Payloads

​Signatures

​Delivery and retries

​Best practices

How webhooks work

Events

Payloads

Signatures

Delivery and retries

Best practices