Skip to main content

Subscribing to Swapcard's webhooks

You can register to Swapcard's 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 (cf Webhook events)
  5. Once you've gathered this information, you have 2 options:

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": {},
  "event_profile": {
  },
  "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: dabe126d047775d1685e1a28eef57381dc2b31688a49959802c1f9b72a569590.

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

Using the developer API to manage your subscriptions​

The developer API provide a set of queries and mutations that allow you to :

Creating a webhook subscription​

GraphQL mutation​

mutation CreateWebhook ($input: CreateWebhookInput!) {
  createWebhook(input: $input) {
    webhook {
      id
      endpoint
      enabled
      hooks
    }
  }
}

Payload​

{
  "input": {
    "eventId": "RXZlbnRfMTgxMDBxOA==",  // Your event ID
    "endpoint": "https://test.com",     // Your endpoint URL where the webhook will be sent
    "secret": "your-secret",            // To generate the hash signature header to validate that the sender is us
    "hooks": [                          // The list of hook you would like to subscribe to :
      "EXHIBITOR_CREATE",               //  * PROFILE_CREATE, PROFILE_UPDATE
      "EXHIBITOR_UPDATE"                //  * EXHIBITOR_CREATE, EXHIBITOR_UPDATE
    ]                                   //  * PLANNING_CREATE, PLANNING_UPDATE
  }
}

Updating an existing webhook subscription​

GraphQL mutation​

mutation UpdateWebhook ($input: UpdateWebhookInput!) {
  updateWebhook(input: $input) {
    webhook {
      id
      endpoint
      enabled
      hooks
    }
  }
}

Payload​

{
  "input": {
    "webhookId": "66a35ec0aec654a42f7648b5",   // The Swapcard's subscription UUID
    "endpoint": "https://test.com",            // The updated endpoint. If not provided, the data won't be changed.
    "hooks": [                                 // The new webhook list. If not provided, the list won't be changed.
      "PROFILE_CREATE",
      "EXHIBITOR_CREATE"
    ]
  }
}

Deleting an existing webhook subscription​

GraphQL mutation​

mutation DeleteWebhook ($input: DeleteWebhookInput!) {
  deleteWebhook(input: $input) {
    webhook {
      id
    }
  }
}

Payload​

{
  "input": {
    "webhookId": "66a35ec0aec654a42f7648b5",   // The Swapcard's subscription UUID
  }
}

Listing event webhook subscriptions​

GraphQL query​

query GetEvent ($eventId: ID!) {
  event(id: $eventId) {
    ...EventDetails
  }
}

fragment EventDetails on Event {
  webhooks(filters: {enabled: true}) {
    id
    endpoint
    enabled
    hooks
  }
}

Payload​

{
  "eventId": "RXZlbnReMTgxMDBxOA=="
}