Skip to main content

Webhooks

A workspace can register its own HTTPS endpoints to be told when things happen. These are separate from an integration's webhook: an integration receives outcomes about the people it launched; a workspace endpoint receives a reduced copy with the integrated-platform identifiers removed.

Registering an endpoint​

A workspace owner adds an endpoint in Console > Integrations > Webhooks:

  • URL - must be https://. The signature proves who sent a payload; it does not hide it, and these payloads are about real people.
  • Events - the event types to receive. The list comes from the server. Leaving every box unticked subscribes the endpoint to all the event types that exist at the moment it is created.

The signing secret is shown once, at creation. It can be rotated through the workspace API (POST /api/v1/webhooks/{id}/rotate-secret), which returns a new secret once and stops the old one working immediately.

Disable stops deliveries to an endpoint and keeps its history. A disabled endpoint cannot be re-enabled; register a new one.

Events​

EventWhen a workspace endpoint receives it
submission.completedA participant launched by one of the workspace's integrations completed their submission in an identified run. The payload is the outcome event without external_context and external_user_sub: submission, session, activity, status and score only.
session.closedA run created by an integration launch was closed. Payload: session_id, activity_id.
session.startedListed and subscribable, but not currently sent.
participant.joinedListed and subscribable, but not currently sent.

Both events that are sent today relate to runs created through integration launches. A session started from the console or the public API produces no webhook events.

Payloads never contain a response, free text, an email address or any contact field.

Signature, retries and idempotency​

Exactly as for integrations - see Webhook signatures and delivery. In short: verify X-Pollinator-Signature over the raw body, return 2xx within 10 seconds, deduplicate on event_id, and expect up to 8 attempts over a few minutes before an event is abandoned.

The delivery log​

Each endpoint has a delivery log in the console, newest first: the event type, the HTTP status code your endpoint returned, the attempt count, any error text and when it was delivered. It is the first place to look when "we stopped getting events".

The log records attempts that got an HTTP response from your endpoint. An attempt that timed out or could not connect is retried but does not appear as a row.

Delivered and abandoned events, with their log rows, are kept for 30 days by default and then deleted. Deleting a session deletes its events too.

Who can do what​

ActionRole
Add, rotate, disable endpoints; read the delivery logOwner

Each of these is recorded in the workspace's audit log.