Skip to main content
Webhook subscriptions are managed at the workspace level. Each subscription defines an HTTPS endpoint and the event types it should receive. You can manage subscriptions in two ways:
  • From the Openlayer dashboard, under your workspace settings.
  • Programmatically, through the REST API.
Only workspace admins can create and manage webhooks, see Roles and permissions for more details.

​
Manage webhooks in the dashboard

The webhooks settings page is where most users create and monitor their subscriptions.
1

Open your workspace settings

Click the workspace name in the upper-left corner, select Workspace Settings, then open the Webhooks section.
2

Add a webhook

On the Webhooks tab, create a new subscription and fill in the form:
  • URL — the HTTPS endpoint that will receive events.
  • Event types — one or more event types to subscribe to.
  • Description — an optional label to help you identify the subscription.
New subscriptions are enabled by default.
3

Copy the signing secret

After you create the subscription, Openlayer shows the signing secret once. Copy it and store it securely — you’ll use it to verify signatures, and it can’t be retrieved later.
4

Edit or delete subscriptions

Each subscription in the list can be edited (to change its URL, event types, description, or enabled status) or deleted. Disabling a subscription pauses deliveries without removing it.

​
View deliveries

Switch to the Deliveries tab to see recent delivery attempts. Each attempt shows whether it succeeded, failed, or is still pending, along with the HTTP status code and response time. Select a delivery to inspect its details, including the response body or error message — useful for debugging an endpoint that isn’t receiving events as expected.
Delivery records are retained for 90 days. For how deliveries and retries work, see the Webhooks overview.

​
Manage webhooks with the REST API

If you’d rather manage subscriptions programmatically — for example, to provision them as part of your infrastructure — use the REST API.

​
Before you begin

All requests are authenticated with an API key passed as a bearer token, and are made against the base URL https://api.openlayer.com/v1: 
Authorization: Bearer YOUR_API_KEY_HERE
See Create an API key if you don’t have one yet. The examples below use {workspaceId}, the UUID of your workspace, which you can find in your workspace settings.

​
Create a webhook subscription

Send a POST request with the endpoint url and the eventTypes you want to subscribe to. 
curl -X POST "https://api.openlayer.com/v1/workspaces/{workspaceId}/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/openlayer",
    "description": "Production alerting",
    "eventTypes": ["test.created", "tests.result.updated"]
  }'
The request body accepts the following fields:
FieldTypeRequiredDescription
urlstringYesThe HTTPS endpoint to deliver events to (max 2048 characters).
eventTypesstring[]YesOne or more event types to subscribe to.
descriptionstringNoAn optional human-readable description (max 500 characters).
enabledbooleanNoWhether the subscription is active. Defaults to true.
The response returns the new subscription’s id and its signing secret: 
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}
The signing secret is returned only once, at creation time. Store it securely — it cannot be retrieved later. You’ll use it to verify webhook signatures. If you lose it, delete the subscription and create a new one.

​
List webhook subscriptions

curl "https://api.openlayer.com/v1/workspaces/{workspaceId}/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "workspaceId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "url": "https://example.com/webhooks/openlayer",
      "description": "Production alerting",
      "eventTypes": ["test.created", "tests.result.updated"],
      "enabled": true,
      "creatorId": "589ece63-49a2-41b4-98e1-10547761d4b0",
      "dateCreated": "2026-01-15T10:00:00Z",
      "dateUpdated": "2026-01-15T10:00:00Z"
    }
  ]
}
The endpoint is paginated with the page and perPage query parameters. Note that the signing secret is never included when listing or retrieving subscriptions.

​
Retrieve a webhook subscription

curl "https://api.openlayer.com/v1/workspaces/{workspaceId}/webhooks/{webhookId}" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"
Returns the same subscription object shown above, or 404 Not Found if the subscription does not exist.

​
Update a webhook subscription

Send a PUT request with the fields you want to change. You can update the url, description, eventTypes, and enabled status. 
curl -X PUT "https://api.openlayer.com/v1/workspaces/{workspaceId}/webhooks/{webhookId}" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypes": ["test.created", "test.updated", "test.deleted"],
    "enabled": false
  }'
Setting enabled to false lets you pause deliveries without deleting the subscription. The response returns the updated subscription object.

​
Delete a webhook subscription

curl -X DELETE "https://api.openlayer.com/v1/workspaces/{workspaceId}/webhooks/{webhookId}" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"
A successful delete returns 204 No Content.

​
List delivery attempts

To debug deliveries, list the recent attempts for a subscription. Each record describes one attempt, including the HTTP status code and response time. 
curl "https://api.openlayer.com/v1/workspaces/{workspaceId}/webhooks/{webhookId}/deliveries" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

{
  "items": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "attemptNumber": 1,
      "success": true,
      "statusCode": 200,
      "responseBody": "{\"status\":\"ok\"}",
      "responseTimeMs": 150,
      "errorMessage": null,
      "dateCreated": "2026-01-21T10:30:05Z"
    }
  ]
}
FieldDescription
attemptNumberWhich attempt this record represents (1 is the initial attempt).
successWhether the attempt received a 2xx response.
statusCodeThe HTTP status code returned, or null if the connection failed.
responseBodyThe first 1 KB of the response body, for debugging.
responseTimeMsHow long the attempt took, in milliseconds.
errorMessageThe error, if the attempt failed.
This endpoint is paginated with the page and perPage query parameters. Delivery records are retained for 90 days. For more on how deliveries and retries work, see the Webhooks overview.