Creating webhooks

You can create webhooks to subscribe to specific events that occur on Swapcard.

Getting started

The destination endpoint designed to capture the data must be equipped to process HTTP POST requests, with each notification delivered in JSON format detailing individual changes as they occur.

To set this up, we require the following details:

1. Your endpoint's URL
2. A secret for request verification
3. The specific event you wish to track (you can locate the event's ID in the "General Information" section within Studio)
4. The particular actions to which you intend to subscribe
5. Once you've gathered this information, please forward it to the Swapcard team. We'll then activate the data flow for your event.

Validating the deliveries

The notifications delivered will contain a hash signature in the X-Signature-256 header. This should be used to validate that the data you received comes from Swapcard. This is done through a HMAC hex digest of the request body using the secret you provided when setting up as the key.

How to test the validation

Let's consider you received a request with the following body:

{
  "context": {},
  "entities": {
    "profiles": []
  },
  "action": "profile_create",
  "datetime": "2024-04-01T00:00:00.000Z"
}

And you provided Swapcard with the secret my_secret.

If the HMAC is properly digested, the hex output should be: c15276975847c1c76edb87325f7b466c006d959acdea9f60e06de3998475135b.

Meaning that in the request received, the X-Signature-256 header should be sha256=c15276975847c1c76edb87325f7b466c006d959acdea9f60e06de3998475135b. Remember to use a constant-time comparison function to avoid timing attacks. Here's an example in golang.