> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Receive real-time HTTP notifications when events happen in your Openlayer workspace.

Webhooks let Openlayer notify your systems the moment something happens in your
workspace, such as a test being created or a test suite finishing a run. Instead
of polling the API, you register an HTTPS endpoint and Openlayer sends it a signed
HTTP `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

<Steps>
  <Step title="Create a subscription">
    A workspace admin registers an HTTPS endpoint and the [event
    types](/security/webhooks/events) it should receive. Openlayer returns a
    **signing secret** that is shown only once. See [Manage
    webhooks](/security/webhooks/manage-webhooks).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Your endpoint verifies and responds">
    Your endpoint [verifies the
    signature](/security/webhooks/verify-signatures), processes the event, and
    responds with a `2xx` status code to acknowledge receipt.
  </Step>
</Steps>

## Delivery

Each event is delivered as an HTTP `POST` 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                                 |

Your endpoint should respond quickly with a `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                                 |

A small random jitter (up to 10%) is added to each delay to avoid synchronized
retries. If all retries are exhausted, the event is marked as `failed` and is not
delivered again.

<Note>
  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](/security/webhooks/verify-signatures#idempotency).
</Note>

## 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](/security/webhooks/manage-webhooks#list-delivery-attempts).

Webhook events and their delivery records are retained for **90 days**, after
which they are automatically deleted.

## Next steps

<CardGroup cols={2}>
  <Card title="Manage webhooks" icon="list" href="/security/webhooks/manage-webhooks">
    Create, update, and delete webhook subscriptions from the dashboard or the
    REST API.
  </Card>

  <Card title="Events and payloads" icon="zap" href="/security/webhooks/events">
    See the available event types and the shape of each payload.
  </Card>

  <Card title="Verify signatures" icon="shield-check" href="/security/webhooks/verify-signatures">
    Validate that incoming requests genuinely came from Openlayer.
  </Card>

  <Card title="Roles and permissions" icon="users" href="/security/roles-and-permissions">
    Review who can manage webhooks in your workspace.
  </Card>
</CardGroup>