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 thewebhook-idheader.type: the event type.createdAt: when the event happened, in ISO-8601 UTC.data.pretest: the pre-test, exactly asGET /pretests/{id}returns it at the time of the event (the example above shows only a few fields). See Results.
ping event arrives with an empty data ({}).
Headers
Create an endpoint
201 and carries the endpoint, with id, status (enabled or disabled) and the secret field, in the format whsec_YOUR_SECRET_HERE.
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.
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 fakePOST.
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.
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:- Remove the
whsec_prefix from the secret and decode the rest from base64. The result is the key. - Build the text
webhook-id+.+webhook-timestamp+.+ raw body. - Calculate the HMAC-SHA256 of that text with the key and encode it in base64.
- Compare with each item in
webhook-signature(separated by spaces, each in the formatv1,<base64>), in constant time. - Reject the request if
webhook-timestampdiffers from your clock by more than 5 minutes.
false and never throws: respond 400.
Respond and process
- Respond with
2xxwithin 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 not2xx (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_readycan arrive beforepretest.completed, and an old attempt can arrive after a newer one. - An event can arrive more than once. Use the
webhook-idto 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, callGET /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.
Read the delivery list
GET /webhook-endpoints/{id}/deliveries returns the last 50 deliveries of that endpoint, newest first.