---
title: "Send a test delivery"
method: POST
path: "/v2/workspaces/{workspace_id}/webhook-tests"
tags: ["Webhooks"]
---

# Send a test delivery

`POST /v2/workspaces/{workspace_id}/webhook-tests`

## Request

- Base URL: `https://api.app.layer.ai/api`
- URL: `https://api.app.layer.ai/api/v2/workspaces/{workspace_id}/webhook-tests`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.app.layer.ai/authorize`, token URL `https://auth.app.layer.ai/oauth/token`)
  - OAuth 2 (client credentials, token URL `https://api.app.layer.ai/api/oauth/token`, scopes: `workspace:write`)

POST a signed sample event to a URL and report what came back, synchronously. Use it to check reachability and your signature verification before spending Creative Units on a real run. The sample carries `type` `inference.completed` with an empty `data` object, and is signed exactly as a real delivery is.

Nothing is charged, and no run is created.

## Path parameters

- `workspace_id` string, uuid, required: Id of the workspace that owns the resource.

## Headers

- `Idempotency-Key` string

## Request body

- WebhookTestRequest
  - `webhook` WebhookInput, required: Where to POST this request's terminal events, and what to include with them.
    - `url` string, required: HTTPS URL that receives a POST when this request reaches a terminal state. Must be publicly reachable; must not redirect. Acknowledge with any 2xx within 10 seconds and do the work asynchronously. Reply 410 to stop delivery permanently.
    - `events` WebhookEventType[], nullable: Narrows what is delivered. Omit to receive every event this request can produce, which is what `expected_events` on the response lists.
    - `metadata` object: Opaque key/value pairs echoed back verbatim in every delivery, for correlating a callback with your own records. At most 10 keys and 1024 bytes in total.

## Response `200`

Successful Response

- WebhookTestResponse
  - `delivered` boolean, required: Whether the receiver acknowledged with a 2xx.
  - `response_status` integer, nullable: HTTP status the receiver returned, or null if it never responded.
  - `latency_ms` integer, required: How long the attempt took, end to end.
  - `error` string, nullable: Why the attempt did not succeed, when it did not.

## Other responses

- `401`: Unauthenticated — missing or invalid Bearer token.
- `403`: Forbidden — insufficient permissions, or the access token lacks the scope the operation requires.
- `404`: Resource not found.
- `409`: The outcome of the request with this `Idempotency-Key` is not known yet: it is still running, or it failed without a stored response. Retry after the number of seconds in `Retry-After`.
- `422`: Invalid input parameters, or an `Idempotency-Key` reused for a different request.
- `429`: Rate limited — retry after the number of seconds in `Retry-After`.
- `500`: Internal server error.

## Changes

- **2026-10-20** `326f3bcdabcc`: 7 info
  - added the required property `error_code` to the response with the `401` status
  - added the required property `error_code` to the response with the `403` status
  - added the required property `error_code` to the response with the `404` status
  - added the required property `error_code` to the response with the `409` status
  - …3 more
- **2026-10-11** `2d86d473cda6`: 2 info
  - the endpoint scheme security `serviceAccount` was added to the API
  - the security scope `workspace:write` was removed from the endpoint's security scheme `oauth2`
- **2026-10-10** `9425712a1f7e`: 2 info
  - the endpoint scheme security `bearerAuth` was added to the API
  - the endpoint scheme security `oauth2` was added to the API
- **2026-09-21** `0aa077697d76`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/layer/apis/layer-rest-api/changes/v2/workspaces/:workspace_id/webhook-tests/post.md)

---

[API](https://skmtc.dev/layer/apis/layer-rest-api.md) · [All operations](https://skmtc.dev/layer/apis/layer-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/layer/apis/layer-rest-api/revisions/326f3bcdabcc?raw)