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)
• Transaction created (transaction.created) (Example)
• Transaction updated (transaction.updated) (Example)
• Transaction deleted (transaction.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:

• Verifying Webhooks Manually.
• How to Verify Webhooks with the Svix Libraries.

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	Payload Example	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.
Transactions updates	Transaction created	transaction.created	Sent when a transaction is created.
Transactions updates	Transaction updated	transaction.updated	Sent when a transaction is updated.
Transactions updates	Transaction deleted	transaction.deleted	Sent when a transaction 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, and Alerts endpoints for more information.

tip

The payload may contain country information in ISO 3166-1 alpha-3 format.

Example: when the customer gets KYC approval

1. When a customer starts a KYC process, your application has their web session details and their wallet address.

2. As they go through the KYC process, several webhook events of various types are created.

3. When the customer gets KYC approval, a customer.updated event is sent to the webhook. The payload includes the customer status with a value of Active ("status": "Active") and the customer ID (customerID).

   {
       "eventType":"customer.updated",
       "payload":{
           ...
           "status": "Active",
           ...
           "customerId":"bc9923ef-37a4-4478-8dca-3bae58049674",
           ...
       }
   }

4. 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 of customerId, 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.