Skip to main content

Subscriptions

To start receiving webhook messages from EventsAir, you will need to create a subscription. The GraphQL API provides mutations and queries to create, update, delete, and list webhook subscriptions.

note

A webhook subscription must:

  • include a unique endpoint URL - you cannot re-use the same URL in another subscription
  • include at least one event type
  • include a description

A webhook subscription may optionally include one or more filters.

Limit

By default, there is a limit of 10 webhook subscriptions per customer.

Creating a webhook subscription​

The createWebhookSubscription mutation allows you to create a webhook subscription by specifying the endpoint URL, a description and one or more event types. For example:

mutation CreateWebhookSubscriptionExample {
  createWebhookSubscription(
    input: {
      url: "https://www.example.com/webhooks"
      webhookEventTypeNames: ["Event.Contact.Created", "Event.Contact.Updated"]
      description: "Example webhook subscription"
    }
  ) {
    webhookSubscription {
      id
    }
  }
}

This operation will create a webhook subscription that sends messages to https://www.example.com/webhooks for the Event.Contact.Created and Event.Contact.Updated event types and return the identifier of the newly created subscription.

Updating a webhook subscription​

The updateWebhookSubscription mutation allows you to update a webhook subscription by specifying the subscription identifier and the new values for the subscription. For example:

mutation UpdateWebhookSubscriptionExample {
  updateWebhookSubscription(
    input: {
      id: "<string>"
      url: "https://www.example.com/webhooks"
      webhookEventTypeNames: ["Event.Contact.Created", "Event.Contact.Updated"]
      description: "Updated webhook subscription"
    }
  ) {
    webhookSubscription {
      id
    }
  }
}

Deleting a webhook subscription​

The deleteWebhookSubscription mutation allows you to delete a webhook subscription by specifying its subscription identifier. For example:

mutation DeleteWebhookSubscriptionExample {
  deleteWebhookSubscription(input: { id: "<string>" }) {
    success
  }
}

This operation will delete the webhook subscription with the specified identifier and returns a Boolean indicating whether the operation was successful.

Listing webhook subscriptions​

The webhookSubscriptions query allows you to list all webhook subscriptions. For example:

query ListWebhookSubscriptionsExample {
  webhookSubscriptions {
    edges {
      node {
        id
        url
        description
        webhookEventTypeNames
        isDisabled
        filters {
          type
          identifier
        }
        createdAt
        createdBy
        lastModifiedAt
        lastModifiedBy
      }
    }
  }
}

Disabling a webhook subscription​

In some cases, you may wish to disable a webhook subscription without deleting it. This stops it from receiving any notifications of activities in EventsAir. The disableWebhookSubscription mutation allows you to disable a webhook subscription by specifying its subscription identifier. For example:

mutation DisableWebhookSubscriptionExample {
  disableWebhookSubscription(input: { id: "<string>" }) {
    id
    isDisabled
  }
}

Enabling a webhook subscription​

If you have disabled a webhook subscription and wish to re-enable it, you can use the enableWebhookSubscription mutation. For example:

mutation EnableWebhookSubscriptionExample {
  enableWebhookSubscription(input: { id: "<string>" }) {
    id
    isDisabled
  }
}

Retrieving the signing secret for a webhook subscription​

To verify the signature of a webhook message, you need the signing secret associated with the webhook subscription. You can use the webhookSubscriptionSigningSecret query to retrieve the signing secret for a webhook subscription by specifying the webhook subscription identifier. For example:

query WebhookSubscriptionSigningSecretExample {
  webhookSubscriptionSecret(id: "<string>") {
    secret
  }
}

See verifying the message signature for further details on how to use the signing secret to verify incoming webhook messages.

Webhook subscription filters​

In some situations, for example if your company manages events for a variety of clients, you may want to filter the messages you receive to only those that are relevant to a specific event or contact store in EventsAir. You can create a webhook subscription with filters to achieve this.

The following GraphQL mutation creates a webhook subscription with two filters, one for a specific event and one for a specific contact store:

mutation CreateWebhookSubscriptionWithFiltersExample {
  createWebhookSubscription(
    input: {
      url: "https://www.example.com/webhooks"
      webhookEventTypeNames: ["Event.Contact.Created"]
      description: "Example webhook subscription with filters"
      filters: [{ identifier: "<guid>", type: EVENT }, { identifier: "<guid>", type: CE_CONTACT_STORE }]
    }
  ) {
    webhookSubscription {
      id
    }
  }
}
Limit

There is a limit of 10 filters per subscription.