Webhooks Overview

IDWise uses webhooks to notify your backend in real time when key events occur during the verification lifecycle — such as a journey completing, a step being submitted, or a KYC renewal coming due. Instead of polling the API for status changes, your system receives an HTTP POST request the moment an event happens.

Webhook Security

We implement the following measures to enhance the security of webhooks:

• Webhook Secret: Customers can secure their webhooks using various authorization mechanisms. IDWise supports basic authentication, bearer token authorization, or custom keys set in the headers for authorization purposes.
• IP Whitelisting: Customers can configure their webhooks to accept requests only from specific IP ranges provided by IDWise, offering enhanced security and control over incoming requests.
• No PII Data: Our webhook events are designed to strictly exclude personally identifiable information (PII). They function solely as notification mechanisms to inform the customer's backend of relevant events.

Webhook Types

IDWise supports multiple webhook types, each triggered at a specific moment in the verification process.

For a full comparison of all webhook types, see IDWise Webhook Types & Use Cases.

Webhook Sequence Diagram

The sequence diagram below shows all webhooks supported by IDWise, highlighting when each webhook is triggered during the verification lifecycle.

sequenceDiagram
    participant User
    participant Your System
    participant IDWise

    User->>IDWise: Start journey

    rect rgba(59, 130, 246, 0.15)
    Note over User,IDWise: Step Submission Phase
    User->>IDWise: Submit step (e.g. ID document)
    IDWise->>Your System: Finished Step Webhook
    User->>IDWise: Submit step (e.g. Selfie)
    IDWise->>Your System: Finished Step Webhook
    end

    IDWise->>Your System: Finished User Steps Webhook
    Note over IDWise,Your System: All user steps submitted

    rect rgba(34, 197, 94, 0.15)
    Note over IDWise: IDWise Processing
    IDWise->>IDWise: Document verification, liveness, AML, rules
    end

    IDWise->>Your System: Finished Journey Webhook
    Note over IDWise,Your System: Final decision ready (Complete / Refer / Rejected)

    rect rgba(249, 115, 22, 0.15)
    Note over Your System,IDWise: Post-Verification Events

    alt Compliance reviewer updates decision
        IDWise->>Your System: Updated Journey Webhook
    end

    alt Manual review requests resubmission
        IDWise->>Your System: Verification Update Required Webhook
        User->>IDWise: Resubmit step
        IDWise->>Your System: Finished Journey Webhook
    end

    alt Compliance team reviews journey
        IDWise->>Your System: Manually Reviewed Webhook (Deprecated)
    end
    end

    rect rgba(139, 92, 246, 0.15)
    Note over Your System,IDWise: Ongoing Monitoring

    alt AML monitoring detects update
        IDWise->>Your System: AML Monitor Update Webhook
    end

    alt Spot check completed
        IDWise->>Your System: Finished Spot Check Webhook
    end
    end

    rect rgba(239, 68, 68, 0.15)
    Note over Your System,IDWise: KYC Renewal

    IDWise->>IDWise: Monitor renewal triggers (daily)
    IDWise->>Your System: Verification Update Required Webhook
    Note over IDWise,Your System: Grace period begins
    Your System->>User: Notify user to resubmit

    alt User resubmits in time
        User->>IDWise: Resubmit document or selfie
        IDWise->>Your System: Finished Journey Webhook
    else Deadline elapsed
        IDWise->>Your System: KYC Renewal Deadline Exceeded Webhook
        Note over IDWise,Your System: Journey status changes to Incomplete
    end
    end

Best Practices

Follow these guidelines when implementing your webhook handler: