Webhooks

Webhooks are a commonly used mechanism to integrate web-based applications. Webhooks allow an application to notify other applications that something has happened. When an activity occurs, the application sends an HTTP POST request to a specified URL. The data sent to this URL is a message from the application that can be used to integrate with it.

Webhooks in EventsAir

Webhooks are a subscription service

Webhooks in EventsAir are a subscription service with a recurring licence fee. This helps us provide the infrastructure and support to ensure a quality integration experience. Please contact your account manager or support for more information.

You can use webhooks to receive notifications about activities that occur within the EventsAir platform, such as a contact being updated or a new registration being created. These are known as webhook event types.

EventsAir provides GraphQL queries and mutations to help manage webhooks as well as a portal to monitor webhook messages.

In order to access these GraphQL features your API key must have the Enable webhooks permission set. This permission is configured in the Users section of the Application Setup screen in EventsAir:

To use webhooks in your integrated application, you generally follow these steps:

• Create an application to receive webhooks via a URL (this URL is known as the webhook endpoint).
• Create a webhook subscription in EventsAir using GraphQL, specifying the webhook event type(s) you want to receive and the webhook endpoint URL.
• In your application, listen for incoming webhook messages requests and:
  • Verify the message signature and timestamp
  • Process the message
  • Return an HTTP 2xx (status code 200-299) response to the webhook message request within a reasonable time-frame (15s).

The following sections provide more details on how to work with webhooks in EventsAir.

Webhook event types

Event types are identifiers in a webhook message that indicate the type of message being sent. When creating a webhook subscription, you can subscribe to one or more event types. This allows you to filter the messages you receive to only those that are relevant to your application.

The Webhook event types page lists all the event types for webhooks in EventsAir.

The GraphQL API also provides a query to list all available webhook event types:

query ListWebhookEventTypesExample {
  webhookEventTypes {
    edges {
      node {
        name
        description
      }
    }
  }
}

Webhook message structure

A webhook message is an HTTP request including headers and body content.

Webhook HTTP headers

When EventsAir sends a webhook message, the HTTP request includes the following headers:

HTTP request header	Description
Webhook-Id	A unique message identifier for the webhook message. This identifier is unique across all messages, but will be the same when the same webhook is being resent (e.g. due to a previous failure).
Webhook-Timestamp	A timestamp indicating when the message was generated (in Unix time format)
Webhook-Signature	The signature of the webhook message, used by client applications to verify its authenticity

These headers are used to verify message authenticity and prevent against potential security threats. See verifying the message signature and timestamp for more information.

Webhook HTTP body

The HTTP body for a webhook message is delivered as JSON data with two top-level properties:

1. The type property defines the webhook event type, so consuming applications can adjust processing based on the incoming message.
2. The data property is the payload of the webhook, an object that contains:
   1. The identifier(s) of the affected entity.
   2. A timestamp property indicating when the action was taken.
   3. A correlationId property that can be used for troubleshooting and implementing idempotency in handling messages.

Webhook message payloads in EventsAir follow a thin payload approach that only contains the identifier(s) of the affected entity. EventsAir is a large and highly configurable platform and customers can use it in different ways. Using thin payloads, customers can query data through the GraphQL API, defining the exact queries for data that meets their needs. This approach is more flexible and efficient than sending full payloads in webhook messages.

Consuming applications can use these identifiers to query the entity through the GraphQL API for detailed information.

The payload might look like:

{
  "type": "Event.Registration.Created",
  "data": {
    "eventId": "<guid>",
    "registrationId": "<guid>",
    "timestamp": "yyyy-MM-ddTHH:mm:ssZ",
    "correlationId": "<guid>"
  }
}