Webhooks

Webhooks allow your application to receive verification results automatically, in real time, as soon as a user completes a workflow. When a session finishes, the platform sends an HTTP POST request with a Content-Type: application/json body to your configured URL containing transaction details, policy decisions, and (optionally) user data.

This means your system receives results automatically as they happen, without needing to check for them. Webhooks are the recommended approach for integrations that need to act on verification outcomes immediately. Common use cases include triggering downstream provisioning, updating a case management system, syncing with a DSAR platform like OneTrust, or logging results to an internal database.

Enabling a Webhook

Webhook settings are found on the Details > Integration page of your workflow, under Webhook Configuration.

1. Set Enable Webhook to Yes.
2. Enter your Webhook URL. Valid URLs must begin with http:// or https:// and cannot include spaces or quotes.
3. Select an Authorization Type to secure the endpoint (see below).
4. Configure any Advanced Configuration options for your use case (see below).

Once enabled and saved, the platform will send a POST request to your URL each time a user completes the workflow. If you previously configured webhooks at the service/step level in Admin 1, note that webhook configuration is now centralized at the workflow level. Steps inherit the workflow's webhook settings automatically.

Authorization Types

The authorization type determines how the platform authenticates with your receiving endpoint. ID DataWeb supports four options:

• None No authentication is applied to the webhook request. The POST is sent without any authorization headers. Use this only for testing or for endpoints that handle their own authentication through other means (e.g., IP whitelisting).

• Basic The platform encodes your username and password as a Base64 string and sends it as a Basic Authorization header with each webhook request. Required fields: Username, Password
  How it works:
  username:password → ZXhhbXBsZVVzZXI6ZXhhbXBsZVBhc3M= The encoded string is sent as: Authorization: Basic ZXhhbXBsZVVzZXI6ZXhhbXBsZVBhc3M=

• OAuth 2.0 The platform uses your client credentials to request an access token from your token endpoint, then sends it as a Bearer Authorization header with each webhook request. This is the most common choice for production integrations with services that support OAuth. Required fields: Client ID, Client Secret, Token URL How it works:
  The platform encodes your credentials and sends them to your token URL: Authorization: Basic <Base64-encoded credentials> Your token endpoint returns an access token:

  {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
  }

The platform includes that token in the webhook request: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

• Custom Header Lets you specify a custom header name and value that will be included with each webhook request. This is useful for services that authenticate via API keys or custom tokens sent in headers. Required fields: Header (the header name, e.g., x-api-key), Value (the header value)

Advanced Configuration

These options control the structure and content of the webhook payload. They are found below the authorization settings on the workflow's Integration page.

Example Webhook Response (Flat Endpoint)

The following is an example of a flat webhook response with Include User Data enabled. Field values have been sanitized.

To include transaction IDs in your webhook response body, enable Add Flat Endpoint.

{
  "endpoint$transaction$asi": "383993a4-b0b0-492e-9140-666876ecc8d0",
  "endpoint$transaction$status": "success",
  "endpoint$transaction$errorCode": "",
  "endpoint$transaction$errorDescription": "",
  "endpoint$transaction$credential": "test",
  "endpoint$transaction$credentialCreationDate": "11/22/2023 14:47:30 UTC",
  "endpoint$transaction$mbun": "3b02bda2-8a5e-40ff-a30b-925040d9d965",
  "endpoint$transaction$sessionCreationDate": "11/22/2023 14:47:30 UTC",
  "endpoint$transaction$appId": "null",
  "endpoint$policyDecision$conclusion": "approve",
  "endpoint$policyDecision$disposition": "positive",
  "endpoint$policyDecision$status": "success",
  "endpoint$policyDecision$message": "",
  "userAttributes$FullName$fname": "John",
  "userAttributes$FullName$lname": "Doe",
  "userAttributes$InternationalTelephone$dialCode": "1",
  "userAttributes$InternationalTelephone$telephone": "1234567890",
  "userAttributes$InternationalAddress$country": "US",
  "userAttributes$InternationalAddress$locality": "CITY",
  "userAttributes$InternationalAddress$route": "123 STREET",
  "userAttributes$InternationalAddress$administrative_area_level_1": "STATE",
  "userAttributes$InternationalAddress$postal_code": "12345"
}

Query String Token Authentication

For webhook integrations that use bearer tokens, such as OneTrust DSAR workflows, you can append the token directly to the webhook URL as a query parameter instead of configuring OAuth 2.0:

https://your-endpoint.com/api/webhook?Authorization=Bearer%20

This approach is simpler to configure but means the token is visible in the URL. Set the bearer token to the maximum expiry acceptable for your use case, and be aware that URLs may appear in server logs.

Best Practices

Use HTTPS. Always configure your webhook URL with https:// to ensure the payload, which may contain PII and policy decisions, is encrypted in transit.

Secure your endpoint. Choose an authorization type appropriate for your environment. For production integrations, Basic, OAuth 2.0, or Custom Header are recommended over None.

Return a 2xx response quickly. Your endpoint should acknowledge receipt with a 200 or 202 status code as promptly as possible. Offload any heavy processing (database writes, downstream API calls) to a background job rather than blocking the response.

Log incoming payloads. Maintain your own logs of received webhook payloads for debugging and auditing. This is especially helpful when troubleshooting delivery issues or verifying that payload content matches expectations.

IP whitelisting. If your endpoint is behind a firewall, you may need to allowlist inbound requests from the ID DataWeb platform. Contact support for the current list of outbound IP addresses.

Troubleshooting

Webhook not firing. Confirm that Enable Webhook is set to Yes and that the workflow has been saved after making changes. Verify that the URL is correctly formatted and reachable from the internet.

Endpoint returning errors. Check that your server is returning a 2xx status code. A 4xx or 5xx response may indicate an authentication mismatch (wrong credentials in the authorization config), a malformed endpoint, or an application error on your side.

Firewall or network issues. If your endpoint is behind a firewall or VPN, ensure that inbound POST requests from the platform are allowed. See the IP whitelisting note above.

Unexpected payload format. If the payload structure doesn't match what you expect, check the Add Flat Endpoint and Add Webhook Wrapper Object toggles. These change the shape of the JSON significantly. Also verify whether Include User Data is toggled to match your expectations.

Query string token expiring. If you're using query string token authentication, the token will eventually expire. Monitor for 401 responses from your endpoint and rotate the token in the webhook URL before expiry.