Overview

The Flow API provides two types of webhooks to help you stay updated on the progress and completion of verification and onboarding flows.

1️⃣ General Flow Webhooks

These webhooks are configured at the flow level and notify you when a flow has been fully completed, including all the associated services.
You can configure these webhooks when creating or editing a flow by clicking the "<>" button (with the tooltip "Integrate SDK") as shown in the following image:

Here, simply enter the URL of your webhook endpoint and click Save. Once configured, Rillis will automatically send notifications to this URL every time a user completes the flow.

2️⃣ Step-by-Step Webhooks

If you want to receive more granular updates as the user progresses through the different steps of the flow (such as onboarding forms or document verification), you can enable step-specific webhooks.
These can be configured by navigating to the "Webhook" tab within each flow. This way, you can capture events as they occur in real-time.

Summary Table of Flow API Webhooks

Webhook Type	Description	Step
`FLOW_COMPLETED`	Triggered when a flow and all related services are fully completed.	Flow completion
`FLOW_REJECTED`	Triggered when a flow is rejected (e.g., final decision of no approval).	Flow completion
`VERIFICATION_IDENTITY_REJECTED`	Triggered when an identity verification is rejected.	Identity Verification
`VERIFICATION_IDENTITY_COMPLETED`	Triggered when an identity verification is approved.	Identity Verification
`VERIFICATION_IDENTITY_UPDATED`	Triggered when an identity verification is manually updated.	Identity Verification
`ONBOARDING_FORM_INDIVIDUAL_COMPLETED`	Triggered when an individual form is completed (pending review).	Onboarding Individual
`ONBOARDING_FORM_INDIVIDUAL_REJECTED`	Triggered when an individual onboarding form is rejected.	Onboarding Individual
`ONBOARDING_FORM_COMPANY_COMPLETED`	Triggered when a company form is completed (pending or approved).	Onboarding Company
`ONBOARDING_FORM_COMPANY_REJECTED`	Triggered when a company onboarding form is rejected.	Onboarding Company

How Webhooks Work

Whenever an event occurs, Rillis sends a POST request to your configured webhook URL containing the event data in JSON format. The payload typically includes:

type: The type of the event (e.g., FLOW_COMPLETED).

timestamp: The time when the event was triggered.

data: The specific details of the event.

Your webhook endpoint must respond with a 200 HTTP status code to confirm receipt. If Rillis does not receive this response, it will automatically retry the notification several times.

🔐 Securing Your Webhooks (Signature Validation)

To ensure that the received information is authentic, unaltered, and truly comes from Rillis, you can configure a Webhook Key in your Flow settings. This key is used to sign the data sent in the webhook payload via HMAC-SHA256.

When enabled, Rillis includes the following custom HTTP headers in every request:

x-signature: The HMAC-SHA256 signature of the payload.

x-timestamp: The Unix timestamp (in seconds) when the signature was generated.

How to Validate the Signature (Step-by-Step)

Step 1: Extract Headers and Payload

Retrieve the x-signature and x-timestamp from the request headers, and capture the raw JSON body.

Step 2: Sort the Payload Recursively

Crucial Step: To guarantee a deterministic result, you must recursively sort the payload object keys alphabetically before stringifying it.

Step 3: Recreate the Signature

Concatenate the timestamp and the stringified sorted payload using a dot (.), then hash it using your secret webhook_key.

Step 4: Compare Signatures Safely

Use a timing-safe comparison to prevent timing attacks. Additionally, validate the timestamp to prevent replay attacks.

Security Best Practices

Never expose your webhook_key: Ensure it is never visible in client-side code, server logs, or error responses.

Use environment variables: Always store the webhook_key securely on your server using environment variables (e.g., .env files).

Validate timestamps: Always check the x-timestamp header against your server's current time to prevent replay attacks (a 5-minute window is recommended).

Use safe comparison: Employ timingSafeEqual (or your programming language's equivalent) when comparing signatures to prevent timing attacks.

Implement rate limiting: Protect your webhook endpoint infrastructure by limiting the number of requests it can receive in a given timeframe.

Overview

1️⃣ General Flow Webhooks#

2️⃣ Step-by-Step Webhooks#

Summary Table of Flow API Webhooks#

How Webhooks Work#

🔐 Securing Your Webhooks (Signature Validation)#

How to Validate the Signature (Step-by-Step)#

Step 1: Extract Headers and Payload#

Step 2: Sort the Payload Recursively#

Step 3: Recreate the Signature#

Step 4: Compare Signatures Safely#

Security Best Practices#