Skip to main content
Instead of calling GET /pretests/{id} from time to time, register an address on your server. Unite makes a signed POST to that address when something changes in a pre-test. The format follows the Standard Webhooks standard. To manage endpoints through the API, the key needs the webhooks:manage scope. See Authentication. Workspace administrators also register, test and remove endpoints in the workspace dashboard, without using a key.

Events

Each endpoint chooses the events it wants to receive. There is also the ping event, used only to test the endpoint.

Delivery body

The body is JSON:
  • id: identifies the event. It is the same value as the webhook-id header.
  • type: the event type.
  • createdAt: when the event happened, in ISO-8601 UTC.
  • data.pretest: the pre-test, exactly as GET /pretests/{id} returns it at the time of the event (the example above shows only a few fields). See Results.
The ping event arrives with an empty data ({}).

Headers

Create an endpoint

The response is 201 and carries the endpoint, with id, status (enabled or disabled) and the secret field, in the format whsec_YOUR_SECRET_HERE.
The secret is shown only once, in this response. The endpoint list never returns it. Keep it in an environment variable on your back end. If you lose it, delete the endpoint and create another one.
Address rules:
  • It must use https, on port 443 (the default).
  • It cannot include a username or password.
  • It must resolve to a public internet address. Private and local addresses are refused.
A refused address responds webhook_url_rejected. Each workspace can have up to 5 endpoints, enabled or not. Beyond that, the response is webhook_endpoint_limit. To list, use GET /webhook-endpoints. To delete, DELETE /webhook-endpoints/{id}: the endpoint and its delivery history are removed, and deliveries still waiting are discarded.

Verify the signature

Every request is signed with the endpoint secret. Verify the signature before trusting the content: anyone who finds out your address can send a fake POST. Use the official Standard Webhooks library. It checks the signature and rejects a webhook-timestamp more than 5 minutes off, which blocks the replay of an old request captured by a third party.
Sign and verify the body exactly as it arrived (the raw bytes). If your framework converts the JSON into an object and then back into text, the signature stops matching. Read the raw body before any conversion.
This only takes the processing out of the response. Real background work (writing to a database, calling other systems, retrying on error) belongs to your task queue: store the event, return 200 and let a worker process it. verify returns the event already converted into an object and throws WebhookVerificationError if the signature does not match or if the webhook-timestamp is too old. Respond 400 in those cases.

Without the library

If you prefer not to use the library, the signature is calculated like this:
  1. Remove the whsec_ prefix from the secret and decode the rest from base64. The result is the key.
  2. Build the text webhook-id + . + webhook-timestamp + . + raw body.
  3. Calculate the HMAC-SHA256 of that text with the key and encode it in base64.
  4. Compare with each item in webhook-signature (separated by spaces, each in the format v1,<base64>), in constant time.
  5. Reject the request if webhook-timestamp differs from your clock by more than 5 minutes.
The same calculation in Python:
Header names are case-insensitive (the Python above lowercases them before reading). In both examples, a format failure (missing or malformed header) returns false and never throws: respond 400.

Respond and process

  • Respond with 2xx within 10 seconds. Beyond that, the attempt counts as a failure.
  • Do the minimum before responding: verify the signature, store the event and return 200. Process the rest in the background.
  • Redirects (3xx) are not followed and count as a failure. Register the final address.
  • Unite does not send from fixed IP addresses. Do not allowlist by IP: signature verification is what guarantees the origin.

Retries

Any response that is not 2xx (or no response within 10 seconds) causes a new attempt. There are up to 12 attempts per delivery, with an increasing interval from 30 seconds up to 1 hour, over about 5 to 6 hours. If all fail, the delivery is left as failed. A delivery that stays pending for more than 7 hours also shows as failed, with lastError equal to expired. The exception is status 410: it means “this address no longer exists”. When your destination responds 410, Unite disables the endpoint (status: "disabled", disabledReason: "gone") and does not try again. Another exception: if the address starts resolving to a private or blocked address, the delivery is closed without a new attempt, with lastError as url_rejected:private_address. If API access is turned off for the workspace, the delivery is also closed without a new attempt, with lastError as feature_disabled. A disabled endpoint no longer receives events and cannot be tested; create another one to receive again. Only respond 410 on purpose. An endpoint is also disabled on its own, with disabledReason: "creator_removed", when the person who created it leaves the workspace or loses access to it. It stops receiving events and cannot be tested; an administrator registers another endpoint. Revoking an API key does not affect endpoints: they belong to the workspace, and administrators manage them in the workspace dashboard.

Order and repeats

  • There is no ordering guarantee. pretest.report_ready can arrive before pretest.completed, and an old attempt can arrive after a newer one.
  • An event can arrive more than once. Use the webhook-id to ignore what you already processed. Store the received ids and discard repeats.
  • The truth is in the GET. The event tells you something changed. For the current state, call GET /pretests/{id}, and do not rely on arrival order.

Test the endpoint

POST /webhook-endpoints/{id}/test sends a signed ping event, like the others. The response is 202, with the delivery id and status: "pending". The result shows up in the delivery list.
A disabled endpoint cannot be tested.

Read the delivery list

GET /webhook-endpoints/{id}/deliveries returns the last 50 deliveries of that endpoint, newest first.
Each item carries: