Skip to main content

Secure webooks

Implement security best practices to protect your webhook endpoints​

Secure your webhook endpoints to ensure that incoming requests genuinely originate from IDnow and have not been tampered with.

Security headers​

When configuring your webhook endpoint in the IDnow dashboard, you can define custom HTTP headers that are sent with every webhook request. IDnow automatically includes these headers in each call. No schema validation is performed.

Steps:

  1. Configure headers: Define the desired headers (e.g. API key or shared secret) in the webhook configuration.
  2. Verify headers: Check that the header values received in the webhook request match the expected ones.

Example patterns:

  • Static token (API Key / Shared Secret): X-Auth-Token: 5eaf37d12c9b4c0987a6f9e1a4f823bf
  • Basic Authentication: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

JWT signature​

All webhook payloads are additionally signed using a JSON Web Token (JWT). You can optionally verify this signature to ensure the authenticity and integrity of the webhook. The JWT is included in the X-Idnow-Signature header of every webhook request.

JWKS endpoint

IDnow exposes its public keys at:

https://auth.dev1.platform.idnow.dev/oidc/.well-known/jwks.json

The JWKS URL is also advertised via the OpenID configuration:

https://auth.dev1.platform.idnow.dev/oidc/.well-known/openid-configuration

Validation Steps

  1. Extract kid from the JWT header.
  2. Fetch JWKS from the endpoint above.
  3. Select the matching public key using the kid.
  4. Verify the signature using RS256.
  5. Validate claims:
    • exp – token not expired
    • iss – issuer matches IDnow
    • aud – token intended for your application

Once the signature and claims are valid, you can safely trust the webhook payload.

IP whitelisting​

Restrict your webhook endpoint to only accept requests from IDnow IP addresses.

info

IDnow maintains a limited and stable list of IP addresses for webhook delivery.

IP ranges:

Add the IP ranges provided by account managers to your firewall or application allow list.

note

Contact your account manager for the current production IP ranges.

TLS requirements​

Your webhook endpoint must support TLS 1.2 or higher. IDnow validates your endpoint's TLS configuration during setup.

Supported TLS versions:

  • TLS 1.2: Supported and recommended
  • TLS 1.3: Supported and recommended