For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Go to app
DocumentationAPI Reference
DocumentationAPI Reference
  • API Reference
    • Introduction
    • Users
    • Taskflow
    • AI Task Builder
    • Studies
    • Representative sample studies
    • study-collections
    • Filter Sets
    • Participant Groups
    • Custom Groups
    • Study Distribution
    • Submissions
    • Bonuses
    • Messages
    • Workspaces
    • Projects
    • Surveys
    • Webhooks
      • Subscribing
      • Receiving
      • Event Delivery and Retry Logic
      • Persistent Failures and Disabling Logic
      • Idempotency and the X-Event-ID Header
      • Handling event order with X-Timestamp
      • Verifying
      • GETList all subscribable event types
      • GETList all secrets
      • POSTCreate/replace a secret
      • GETList all subscriptions
      • POSTCreate a subscription
      • GETRetrieve a subscription
      • POSTConfirm a subscription
      • DELDelete a subscription
      • PATCHUpdate a subscription
      • GETGet subscription events
    • Invitations
    • Reward Recommendations
    • Testing
    • Well Known Endpoints
Go to app
LogoLogo
On this page
  • Listing event types
  • Creating a secret
  • Subscribing to an event
  • Confirming the subscription
API ReferenceWebhooks

Subscribing

|View as Markdown|Open in Claude|
Was this page helpful?
Previous

Webhooks

Next

Receiving

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.