Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with ExpressConsent. With webhooks, your backend can receive snapshot data real-time, making it easier to integrate consent records into your existing systems.

Registering webhooks

To register a new webhook, you need to have a URL that ExpressConsent can call and POST the relevant snapshot data to. You can configure a new webhook from the ExpressConsent dashboard under Settings > Webhooks.

You can optionally configure a webhook secret to enable HMAC signature verification for added security.

Now, whenever a new snapshot is captured, the relevant data is sent by ExpressConsent to your specified endpoint. In the next section, we'll look at how to consume these webhook notifications.

Consuming webhooks

Here is an example of a webhook payload:

Example webhook payload

{
  "transactionId": "xyzzy-12345",
  "domain": "example.com",
  "downloadURL": "https://storage.googleapis.com/your-bucket/path/snapshot-1686233200-12345.png",
  "createdAt": "2023-06-08T14:06:40.000Z",

  "ip": "198.51.100.23",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
  "anuraData": {
    // Anura data included if toggled in the snapshot request
    "result": "good", // Anura result
    "adblocker": false // Whether the user has an adblocker installed
  },
  "customMetadata": {
    "phoneNumber": "555-123-4567",
    "formName": "lead-generation"
  },
  "leadValidationId": "pkg_abcd1234",
  "subGroupIds": ["group1", "group2"]
}

The payload contains details about the captured snapshot, including its download URL and any custom metadata you provided.

The downloadURL field is only included when Auto-Collect is enabled for your organization. When Auto-Collect is disabled, you'll need to use the API to retrieve snapshot URLs after collection.

In your endpoint, once you have completed processing, make sure to send a 200 response back to confirm receipt of the webhook. This ensures that ExpressConsent knows that your endpoint has received the webhook and that it should not be resent.

See all fields

Event types

Name
transactionId
Description
Unique identifier linking back to the original snapshot request.
Name
domain
Description
The domain on which the consent snapshot was captured.
Name
downloadURL
Description
Time-limited URL where the snapshot image can be downloaded (expires after 7 days but can be regenerated). Only included when Auto-Collect is enabled.
Name
createdAt
Description
ISO 8601 timestamp indicating when the snapshot was created.
Name
ip
Description
Client IP.
Name
userAgent
Description
Client User-Agent captured during the sign step, when available.
Name
anuraData
Description
Anura fraud detection data, if enabled for your organization.
Name
customMetadata
Description
Arbitrary key/value pairs you supplied when creating the snapshot (e.g. phoneNumber, formName).
Name
leadValidationId
Description
The Lead Validation ID that groups this snapshot with others from the same session.
Name
subGroupIds
Description
Array of sub-group identifiers associated with this snapshot, if applicable.

Example payload

{
  "transactionId": "xyzzy-12345",
  "domain": "example.com",
  "downloadURL": "https://storage.googleapis.com/your-bucket/path/snapshot-1686233200-12345.png",
  "createdAt": "2023-06-08T14:06:40.000Z",

  "ip": "198.51.100.23",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
  "anuraData": {
    "result": "good",
    "adblocker": false
  },
  "customMetadata": {
    "phoneNumber": "555-123-4567",
    "formName": "lead-generation"
  },
  "leadValidationId": "pkg_abcd1234",
  "subGroupIds": ["group1", "group2"]
}