POST request whenever a subscribed event occurs.
Common use cases include:
- Alerting on-call engineers when tests start failing in production.
- Triggering CI/CD pipelines or downstream jobs when a test suite finishes.
- Synchronizing test definitions between Openlayer and your own systems.
How it works
Create a subscription
A workspace admin registers an HTTPS endpoint and the event
types it should receive. Openlayer returns a
signing secret that is shown only once. See Manage
webhooks.
An event occurs
When a subscribed event happens in your workspace (for example, a test is
created), Openlayer builds an event payload and queues it for delivery.
Openlayer delivers the event
Openlayer sends an HTTP
POST request to your endpoint with the event
payload as JSON and a set of signature headers.Your endpoint verifies and responds
Your endpoint verifies the
signature, processes the event, and
responds with a
2xx status code to acknowledge receipt.Delivery
Each event is delivered as an HTTPPOST request with a JSON body and the
following characteristics:
| Property | Value |
|---|---|
| Method | POST |
| Content type | application/json |
| Transport | HTTPS only — endpoints served over plain HTTP are never called |
| Connection timeout | 5 seconds |
| Response timeout | 10 seconds |
| Redirects | Not followed (a 3xx response is treated as a failure) |
| Success criterion | Any 2xx response status code |
2xx status code. If you need to do
expensive work, acknowledge the event first and process it asynchronously.
Retries
If a delivery fails — your endpoint returns a non-2xx status code, the
connection times out, or the request errors — Openlayer retries the delivery up
to 3 times using exponential backoff with jitter:
| Attempt | Approximate delay after the previous attempt |
|---|---|
| Initial | Immediate |
| Retry 1 | ~5 seconds |
| Retry 2 | ~5 minutes |
| Retry 3 | ~30 minutes |
failed and is not
delivered again.
Because deliveries are retried, your endpoint may receive the same event more
than once. Use the
webhook-id header to deduplicate events. See Verifying
signatures.Delivery logs and retention
Every delivery attempt is recorded, including the HTTP status code, response time, and any error message. You can inspect recent attempts for a subscription through the deliveries endpoint. Webhook events and their delivery records are retained for 90 days, after which they are automatically deleted.Next steps
Manage webhooks
Create, update, and delete webhook subscriptions from the dashboard or the
REST API.
Events and payloads
See the available event types and the shape of each payload.
Verify signatures
Validate that incoming requests genuinely came from Openlayer.
Roles and permissions
Review who can manage webhooks in your workspace.