Configure Webhook URLs

Configure webhook URLs to receive real-time notifications from IDWise when key verification events occur. Before setting up a webhook in the portal, create a publicly accessible HTTP endpoint on your backend to receive the notifications.

Prerequisites

Before configuring a webhook, ensure your endpoint meets these requirements:

Publicly accessible — IDWise must be able to reach your URL over the internet.
Returns HTTP 200 — Your endpoint must respond with a 200 status code to confirm receipt. IDWise uses this during testing and delivery.
Handles JSON payloads — Each notification is delivered as a JSON POST request containing the event details.
Idempotent — Your handler may receive the same event more than once (e.g., during retries). Ensure processing the same eventId multiple times produces the same result.

Setting Up a Webhook

Navigate to Developer's Area → Webhooks tab, then click Create a Webhook. The setup wizard walks you through three steps: General, Authentication, and Testing.

Step 1: General

Configure the basic webhook settings:

Field	Description
Environment	Select `Live` for production events or `Sandbox` for testing.
Webhook Type	Choose which event triggers this webhook (e.g., Finished Journey, Finished Step). See Webhook Types for all available types.
URL	The endpoint URL where IDWise sends the webhook `POST` requests.
Error Reporting Emails	(Optional) Email addresses to notify when IDWise is unable to deliver the webhook after multiple retry attempts.

Click Next to proceed to authentication.

Step 2: Authentication

Secure your webhook endpoint by selecting an authentication method:

Method	Description
No Authentication	IDWise sends the webhook without any authentication credentials.
Basic Authentication	IDWise includes a `Username` and `Password` in the request headers using HTTP Basic Auth.
Bearer Token	IDWise includes a bearer token in the `Authorization` header.

Custom HTTP Headers

You can add custom key-value headers to every webhook request — useful for API keys, custom tokens, or any additional authentication your endpoint requires. Add headers by entering a Key and Value pair in the Custom HTTP Headers section.

Click Next to proceed to testing.

Step 3: Testing

Before saving, test your webhook to verify that your endpoint is reachable and responding correctly:

Click Test Webhook.
IDWise sends a test request to your configured URL.
Your endpoint must return HTTP 200 for the test to pass.

Once the test passes, click Save to activate your webhook.

⚠️
If the test fails, verify that your URL is publicly accessible, responds with HTTP 200, and that any authentication credentials are correct.

Testing During Development

During development, you can use webhook.site to generate a temporary public URL that captures incoming webhook requests. This is useful for inspecting payloads without deploying your own endpoint.

IDWise supports adding multiple webhook URLs for the same event type, so you can configure both your development URL and your production endpoint simultaneously.