Guides
Check Types
Useful Resources
Webhooks Guide
Listen for events on your ComplyCube account so your integration can automatically trigger reactions.
ComplyCube uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a check has concluded.
Not all ComplyCube integrations require webhooks. Keep reading to learn more about what webhooks are and when you should use them.
What are webhooks?
Webhooks refer to a combination of elements that collectively create a notification and reaction system within a larger integration.
Metaphorically, webhooks are like a phone number that ComplyCube calls to notify you of your account activity. The activity could be that a document check is complete. The webhook endpoint is the person answering that call who takes actions based upon the specific information it receives.
Non-metaphorically, the webhook endpoint is just more code on your server. The webhook endpoint has an associated URL (e.g., https://example.com/webhooks). The ComplyCube notifications are Event objects. This object contains all the relevant information about what just happened, including the type of event and the data associated with that event. The webhook endpoint uses the event details to take any required actions, such as putting a temporary hold on a customer's account or transaction.
What are the components of a webhook?
ComplyCube Webhooks integration includes the following:
- Events. An action or change in data that generates notifications. Webhooks can be used to create alerts that trigger these events. For the list of support event types, see the Webhooks API page.
- Subscriptions. Configured in the developer portal or via API to subscribe to notifications associated with a specific event type.
- Notification URL. The configurable service in the application to which alerts are sent.
- Notification body. Details about the object associated with the event.
When to use webhooks?
Many events that occur within the ComplyCube account have synchronous results – immediate and direct – to an executed request. For example, a successful request to create a client immediately returns a
client object. Such requests don’t require webhooks, as the key information is already available.On the other hand, Checks are asynchronous: happening later and not directly in response to your code’s execution. With these events, ComplyCube needs to notify your integration about changes to an object's status, so your integration can take subsequent steps.
The specific actions your webhook endpoint may take differs based on the event. Some examples include:
- Decide to accept or reject a customer's request to be on-boarded onto your platform based on a check outcome.
- Alerted by our continuous monitoring engine when a customer has a potential match, as we update our databases in real-time.
Verify the webhook signatures using our official libraries
ComplyCube signs the webhook events it sends to your endpoints by including a signature in each event’s
ComplyCube-Signature header. This lets you verify that the events were sent by ComplyCube, not by a third party. You can verify signatures using our official libraries or manually using your own solution.Use one of our official libraries to verify signatures. You perform the verification by providing the event payload, the
ComplyCube-Signature header, and the endpoint’s secret. If verification fails, ComplyCube returns an error.Node.js
Python
PHP
.NET
1
const { EventVerifier } = require('@complycube/api')
2
3
// Provide your webhook secret to the EventVerifier
4
const webhookSecret = process.env.COMPLYCUBE_WEBHOOK_SECRET;
5
const eventVerifier = new EventVerifier(webhookSecret);
6
7
// This example uses Express to receive webhooks
8
const app = require('express')();
9
10
// Use body-parser to retrieve the raw body as a buffer
11
const bodyParser = require('body-parser');
12
13
// Match the raw body to content type application/json
14
app.post('/webhook', bodyParser.json(), (request, response) => {
15
const signature = request.headers['ComplyCube-Signature'];
16
17
let event;
18
19
try {
20
event = eventVerifier.constructEvent(JSON.stringify(request.body), signature);
21
}
22
catch (err) {
23
response.status(400).send(`Webhook Error: ${err.message}`);
24
}
25
26
// Handle the event
27
switch (event.type) {
28
case 'check.completed': {
29
const checkId = event.payload.id;
30
const checkOutCome = event.payload.outcome;
31
console.log(`Check ${checkId} completed with outcome ${checkOutCome}`);
32
break;
33
}
34
case 'check.pending': {
35
const checkId = event.payload.id;
36
console.log(`Check ${checkId} is pending`);
37
break;
38
}
39
// ... handle other event types
40
default: {
41
// Unexpected event type
42
return response.status(400).end();
43
}
44
}
45
46
// Return a response to acknowledge receipt of the event
47
response.json({received: true});
48
});
49
50
app.listen(4242, () => console.log('Running on port 4242'));
Copied!
1
import json
2
import flask
3
from flask import request
4
import complycube.eventverifier as ccevnt
5
6
# Sample flask app
7
app = flask.Flask(__name__)
8
9
# Provide your webhook secret to the EventVerifier
10
verifier = ccevnt.EventVerifier(os.getenv('COMPLYCUBE_WEBHOOK_SECRET'))
11
12
@app.route('/webhook', methods=['POST'])
13
def webhook():
14
if not request.headers.has_key('Complycube-Signature'):
15
return jsonify({'received':'False'}), 400
16
signature = request.headers['ComplyCube-Signature']
17
try:
18
event = verifier.construct_event(request.get_data(),signature)
19
check_id = event.payload['id']
20
if event.type == 'check.completed':
21
check_outcome = event.payload['outcome']
22
print('Check %s completed with outcome %s' % (check_id,check_outcome))
23
elif event.type == 'check.pending':
24
print('Check %s is pending' % check_id)
25
# ... Handle other expected events
26
else:
27
return jsonify({'received':'False'}), 400
28
except ccevnt.VertificationError:
29
return jsonify({'received':'False'}), 400
30
31
return jsonify({'received':'True'}), 200
32
app.run()
33
Copied!
1
use ComplyCube\ComplyCubeClient;
2
use ComplyCube\Model\Event;
3
use ComplyCube\EventVerifier;
4
use ComplyCube\Exception\VerificationException;
5
6
header("Access-Control-Allow-Origin: *");
7
header("Content-Type: application/json; charset=UTF-8");
8
header("Access-Control-Allow-Methods: POST");
9
header("Access-Control-Max-Age: 3600");
10
header("Access-Control-Allow-Headers: Content-Type, Authorization, Complycube-Signature, X-Requested-With");
11
define("SIGNATURE_KEY", 'ComplyCube-Signature');
12
13
$data = file_get_contents('php://input');
14
$verifier = new \ComplyCube\EventVerifier('WEBHOOK_SECRET');
15
$headers = apache_request_headers();
16
17
try {
18
if (!isset($headers[SIGNATURE_KEY])) {
19
http_response_code(400);
20
return;
21
}
22
$event = $verifier->constructEvent($data, $headers[SIGNATURE_KEY]);
23
switch ($event->type) {
24
case "check.completed":
25
$outcome = $event->payload->outcome;
26
# do completed check processing
27
break;
28
case "check.pending":
29
# do pending check processing
30
break;
31
default:
32
http_response_code(400);
33
return;
34
}
35
http_response_code(200);
36
return;
37
} catch (\ComplyCube\Exception\VerificationException $e) {
38
http_response_code(400);
39
return;
40
}
41
Copied!
1
using Microsoft.AspNetCore.Mvc;
2
using Microsoft.Extensions.Primitives;
3
4
namespace ComplyCube.Net.Example.Controllers
5
{
6
[ApiController]
7
[Route("[controller]")]
8
public class CCEventsController : ControllerBase
9
{
10
[HttpPost]
11
public IActionResult Post([FromBody] string payload)
12
{
13
var re = Request;
14
StringValues payloadSignature;
15
re.Headers.TryGetValue("ComplyCube-Signature", out payloadSignature);
16
var evr = new EventVerifier("WEBHOOK_SECRET");
17
var receivedEvent = evr.ConstructEvent(payload, payloadSignature);
18
switch (receivedEvent.type)
19
{
20
case "check.completed":
21
object outcome;
22
if(receivedEvent.payload.TryGetValue("outcome", out outcome))
23
{
24
// do completed check processing
25
}
26
break;
27
case "check.pending":
28
// do pending check processing
29
break;
30
default:
31
return StatusCode(400);
32
}
33
return (StatusCode(200, receivedEvent));
34
}
35
}
36
}
Copied!
Verify the webhook signatures manually
- 1.Extract the
complycube-signaturefrom the HTTP headers. - 2.Determine the expected signature by computing an HMAC with the SHA256 hash function. Use your webhook's secret as the key, and use the
request bodystring as the message. - 3.Compare the signature in the header to the expected signature.
Best Practices
Event types
You should configure your webhook endpoints to receive only the types of events required by your integration. Listening for extra events (or all events) will put undue strain on your server and is not recommended.
Handle duplicate events
Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is by logging the events you’ve processed and then not processing already-logged events.
Order of events
ComplyCube does not guarantee the delivery of events in the order they are generated. Your endpoint should not expect delivery of events in a given order and should handle this accordingly. You can also use the API to fetch any missing objects.
Receive events with an HTTPS server
If you use an HTTPS URL for your webhook endpoint, ComplyCube will validate that your server's connection is secure before sending your webhook data. For this to work, you must correctly configure your server to support HTTPS with a valid server certificate.
Last modified 18d ago