Subscribing

Listing event types

To get started, make a GET request to /api/v1/hooks/event-types to retrieve an up-to-date list of all the event types that we currently support. All event types will follow the noun.verb pattern, e.g. study.status.change.

Make a note of the event type you’d like to subscribe to. You’ll need this later when setting up a subscription.

Creating a secret

In order to subscribe to an event, you’ll need to first set up a secret. Secrets are used to verify the authenticity of our webhook requests to your system. It allows you to prove we have sent them and the payload hasn’t been fiddled with. There is more about that in the Verifying section below.

Make a POST request to /api/v1/hooks/secrets/ with the payload below. This will create a new secret for your workspace and be returned in the response body. Keep this safe, and note that you can only have one active secret per workspace at a time.

1
{"workspace_id": <workspace_id>}

Subscribing to an event

Next, make a POST request to /api/v1/hooks/subscriptions/ with the payload below to subscribe to your desired event.

Note. <target_url> must be use https:// and be publicly accessible i.e. not https://localhost.

1
{"workspace_id": <workspace_id>, "event_type": <event_type>, "target_url": <target_url>}

If successful, the endpoint will return a response that includes:

• An id field in the body - This is the unique identifier for your subscription.
• An X-Hook-Secret header - Used to confirm your intention to subscribe to the desired event type.

Make a note of both the id and the X-Hook-Secret. We’ll use these to confirm our intention to subscribe to the desired event type.

Confirming the subscription

Make a POST request to /api/v1/hooks/subscriptions/<subscription_id> with the payload below. Replace <subscription_id> with the value of the X-Hook-Secret header in the previous subscription request.

1
{"secret": <x-hook-secret>}

If subscription confirmation is successful, you should receive a 200 status code.