Webhooks
ComPilot uses webhooks to send notifications to your app in real time. This allows for seamless integration between ComPilot and your app, and allows you to automate workflows.
The webhooks can be configured to send notifications for the these types of events.
- Customer created (
customer.created
) (Example) - Customer updated (
customer.updated
) (Example) - Customer deleted (
customer.deleted
) (Example) - Scenario execution (
send.scenario
) (Example) - Verification flow execution (
send.verification.flow
) (Examples) - Alert created (
alert.created
) (Example) - Alert updated (
alert.updated
) (Example) - Alert deleted (
alert.deleted
) (Example)
By listening to the data sent by the webhooks, your application can be kept in synchronization with your customer data in the ComPilot Dashboard.
The customer.updated
events are extremely important. When you receive a customer.updated
event, you can use the ComPilot API to retrieve the customer's details from ComPilot and update your customer database. For an example, see When the customer gets KYC approval, below.
The webhooks are configured in the Webhooks page on the ComPilot Dashboard. To access the Webhooks page, in the Dashboard menu, select Settings > Webhooks. The webhooks allow for highly granular control of the information they receive. They can be used to allow your application to react to events that happen in your customers' identity verification process, and afterward. You can configure multiple webhooks to receive different data. For example, you can configure one webhook that receives user profile updates and another that receives alerts updates.
Adding a webhook
To add a webhook, click the + Add new webhook button. The webhook configuration sidebar is displayed on the right of the screen.
In the Parameters pane of the sidebar, there are three fields.
- Name: Enter the name of the webhook.
- Notification URL: Enter the URL of the webhook that will receive the notifications.
- Secret parameter: The shared secret that is used to secure the webhook. This is automatically generated, and can be shown or copied by clicking the buttons below it.
You should always verify the payloads that your webhook receives. The ComPilot webhooks system is built on Svix. You can either verify the payload manually (using pure JavaScript) or you can use the Svix libraries to do this. For more information, see:
Both those pages are on the Svix documentation site.
Notification configuration
There are eight different types of notification that webhooks can receive. You can choose which you want to receive by toggling them on and off in the Customer updates, Scenario Executions, and Alerts updates panes. They are described in the following table.
Pane | Type | Description | |
---|---|---|---|
Customer updates | Customer created | customer.created | Sent when a customer is created. Includes result. |
Customer updates | Customer updated | customer.updated | Sent when a customer is updated. Includes result. |
Customer updates | Customer deleted | customer.deleted | Sent when a customer is deleted. Includes result. |
Scenario Executions | Scenario executions | send.scenario | Sent when a scenario is executed. Includes result and user data. |
Scenario Executions | Verification flow | send.verification.flow | Sent when a verification flow is executed. Includes result, user data, and, where relevant, Scorechain and IPQualityScore results. |
Alerts updates | Alert created | alert.created | Sent when an alert is created. |
Alerts updates | Alert updated | alert.updated | Sent when an alert is updated. |
Alerts updates | Alert deleted | alert.deleted | Sent when an alert is deleted. |
You can see payload examples by clicking the down arrows at the right of the screen.
Testing the webhook
Once you have configured the webhook, you can click the Run test button at the top of the pane to test it.
Editing a webhook
To edit a webhook, click its name on the Manager tab of the Webhooks. The webhook editing sidebar is displayed on the right of the screen.
Webhook logs
On the Logs tab of the Webhooks page, there is a searchable list of recent webhook deliveries. When you click on a delivery, a sidebar opens on the right of the screen and further information about the delivery is displayed.
You can also resend the payload by clicking the Resend button at the top right of the sidebar.
Using the webhook payload
Each payload contains the ID of the relevant resource. When a payload is received, the application should use the ComPilot API to get data connected with the resource.
See Customers endpoints, Scenarios endpoints, and Alerts endpoints for more information.
The payload may contain country information in ISO 3166-1 alpha-3 format.
Example: when the customer gets KYC approval
When a customer starts a KYC process, your application has their web session details and their wallet address.
As they go through the KYC process, several webhook events of various types are created.
When the customer gets KYC approval, a
customer.updated
event is sent to the webhook. The payload includes the customer status with a value ofActive
("status": "Active"
) and the customer ID (customerID
).{
"eventType":"customer.updated",
"payload":{
...
"status": "Active",
...
"customerId":"bc9923ef-37a4-4478-8dca-3bae58049674",
...
}
}When your application receives this payload, it can use the Get customer details by customerId endpoint to get all the customer's details.
In the following example,
<customerId>
should be replaced by the value ofcustomerId
, and<TOKEN>
is your API key. See ComPilot API.const https = require('follow-redirects').https;
const fs = require('fs');
let options = {
'method': 'GET',
'hostname': 'api.compilot.ai',
'path': '/customers/<customerId>/details',
'headers': {
'Accept': 'application/json',
'Authorization': 'Bearer <TOKEN>'
},
'maxRedirects': 20
};
const req = https.request(options, (res) => {
let chunks = [];
res.on("data", (chunk) => {
chunks.push(chunk);
});
res.on("end", (chunk) => {
let body = Buffer.concat(chunks);
console.log(body.toString());
});
res.on("error", (error) => {
console.error(error);
});
});
req.end();The response from the endpoint will contain all the customer's details, including the wallet address. By matching wallet addresses, you can link the customer ID and their details to their web session. You can then populate your database with this information.