Links

Webhooks

This page provides an overview of webhooks that Corbado uses to talk to your system and existing user base.

Overview

1. Webhooks testing (optional)

To ensure that your webhooks are working properly and returning the correct response, you can define test data to check the two most important actions: requesting login information and password verification.
We then constantly monitor your backend (webhooks URL) by making requests (coming soon).

1.1 Username and password verification

Please provide a valid pair of username and password. This test will check if the password verification of your existing authentication is connected properly.

1.2 Non-existing username

Please provide a username (email address, phone number) that does NOT exist in your database. This test will check if non-existing users are handled properly.

2. Webhooks requests

Webhook requests from Corbado sent to your backend follow this payload structure:
{
"id": "who-1234567890", // Unique ID per webhook request
"projectID": "pro-1234567890", // Your project ID from the developer panel
"action": "authMethods", // The specific action of the webhook request, see table below
"data": {
// Data object dependent on action
}
}
The action is sent as a header (X-Corbado-Action) as well. This makes it easier for you to unserialize the payload into an action dependent entity / model by taking the action from the header instead of taking it from the payload itself.

3. Webhooks responses

Webhook responses from your backend sent to Corbado follow this payload structure:
{
"responseID": "d5a80602-a771-4532-8cc8-6d4a9003d92a", // A response ID you can set in your backend for debugging
"data": {
// Data object dependent on action
}
}

4. Webhooks actions

The following webhooks actions exist:
Action
Description
This action returns if the user already exists in the user database and which authentication methods already exist.
This action verifies if the provided username and password combination of the existing authentication is valid.

5. Backend implementation

To make the implementation of the webhook endpoint in your backend as smooth as possible we provide webhook functionality in our SDKs. Plus, they come with entities / models for request and response (dependent on action) and ease authentication handling for you. We highly encourage you to use them.