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

# Receive Platform Webhooks

> Subscribe to workspace events, verify their signature and check delivery history.

A webhook tells **your backend** when something changes in Layarva. Calling the Platform API sends an instruction to Layarva; receiving a webhook lets Layarva notify you of the result.

> [!NOTE]
>
> If an endpoint returns `503`, stop the workflow and retry later when instructed, or contact support with the response `requestId`. Do not repeatedly create subscriptions while the service is unavailable.

## What you need

* A Platform / Workspace API key with `webhooks.manage` to create, pause or archive a subscription, and `webhooks.read` to view subscriptions and delivery history.
* A receiver you control at a **public HTTPS hostname**, on port 443.
* A separate random signing secret, saved securely on your backend.

Use the [Postman setup](https://docs.layarva.com/developers/platform-quickstart.md) for authenticated API requests. Paths below are relative to your workspace base URL. POST, PATCH and DELETE require a new [Idempotency-Key](https://docs.layarva.com/developers/platform-request-keys.md) for each new operation; reuse it only when retrying that same operation.

> [!WARNING]
>
> A signing secret is **not** your Platform API key. Never send your Platform key to the webhook receiver or expose either secret in browser code, logs or this documentation page.

## Step 1: Generate and save the signing secret

Generate it once on your own computer or backend using Node.js:

```javascript theme={null}
import { randomBytes } from "node:crypto";
const signingSecret = randomBytes(32).toString("base64url");
// Save signingSecret securely on your backend before creating the subscription.
```

The API accepts 32–256 base64url characters: letters, digits, `_` and `-`. Layarva never returns this secret after creation. Keep your saved copy to verify deliveries.

## Step 2: Create the subscription

Send **POST** `/webhooks` with your Platform Bearer key, `Content-Type: application/json` and an Idempotency-Key:

```json theme={null}
{
  "name": "Playlist notifications",
  "url": "https://YOUR_PUBLIC_HOST/layarva-events",
  "events": [
    "playlist.ready",
    "publication.succeeded",
    "publication.failed"
  ],
  "signingSecret": "YOUR_SEPARATELY_GENERATED_SIGNING_SECRET"
}
```

Replace the host and secret before sending. Save the returned `data.id` as `webhook_id`. A workspace can have at most ten non-archived subscriptions, including paused subscriptions.

The receiver URL must not contain a username, password, query string or fragment. Private/local destinations and IP-literal URLs are not supported. Redirects are not followed: configure the final HTTPS address directly.

## Step 3: Choose events that match your workflow

| Event | Meaning |
| - | - |
| `platform.command.completed` | A Platform API change was accepted and applied; it does not confirm later asynchronous work finished |
| `library.upload.committed` | Verification succeeded and a Library asset is available |
| `library.upload.failed` | Upload verification failed |
| `playlist.ready` | An immutable Ready version was created |
| `publication.succeeded` | Publication processing succeeded, not proof that every Screen has played it |
| `publication.failed` | Publication processing failed |
| `offline.export.ready` | An offline package was built, not proof that a Player imported or played it |

An event contains only its identifiers, workspace, name, time and, where applicable, resource/operation references. It does not include file contents or API credentials. Use your authenticated API to read the resource if you need more details.

Example event shape; these are placeholder values, not a real delivery:

```json theme={null}
{
  "id": "YOUR_EVENT_ID",
  "event": "playlist.ready",
  "workspaceId": "YOUR_WORKSPACE_ID",
  "occurredAt": "2026-10-13T10:00:00.000Z",
  "resourceId": "YOUR_READY_VERSION_ID"
}
```

## Step 4: Verify each request before processing

Layarva sends a JSON POST to your receiver with these headers:

```http theme={null}
Content-Type: application/json
X-Layarva-Event-Id: YOUR_EVENT_ID
X-Layarva-Delivery: YOUR_DELIVERY_ATTEMPT_ID
X-Layarva-Timestamp: UNIX_TIMESTAMP_SECONDS
X-Layarva-Signature: sha256=HEX_HMAC_SIGNATURE
```

The signature is **HMAC-SHA256** of:

```text theme={null}
timestamp + "." + eventId + "." + rawRequestBody
```

Verify using the **original body bytes**. Do not parse and stringify JSON first: changing spaces or key order changes the signature. Keep the receiver's clock accurate and reject timestamps more than five minutes away from its current time.

This Node.js helper verifies the signature without changing the body:

```javascript theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

export function validPlatformSignature({ rawBody, timestamp, eventId, signature, secret }) {
  if (!Buffer.isBuffer(rawBody) || rawBody.length > 16 * 1024 ||
      typeof timestamp !== "string" || !/^\d{10}$/.test(timestamp) ||
      Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300 ||
      typeof eventId !== "string" || !eventId ||
      typeof signature !== "string" || !/^sha256=[a-f0-9]{64}$/.test(signature)) {
    return false;
  }
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(timestamp + "." + eventId + ".")
    .update(rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
```

Receiver handling order:

1. Capture raw body bytes with a **16 KiB** limit. If using Express, use `express.raw({ type: "application/json", limit: "16kb" })` on this route **before** any JSON body parser.
2. Call the helper with the three headers and your saved signing secret. Reject an invalid signature or timestamp without processing the event.
3. Parse the verified JSON. Check that `workspaceId` is your workspace and body `id` matches `X-Layarva-Event-Id`.
4. Save the event durably with a unique constraint on its event ID. An already-saved ID is a duplicate, not a new action.
5. Return a small **2xx** response promptly, including for an already accepted duplicate. Process longer-running work asynchronously from your saved event.

Save the event and your processing state before returning success; otherwise a crash could lose an acknowledged event. Do not use an in-memory set as your only duplicate protection.

## Step 5: Handle retries safely

Delivery is **at-least-once**: the same event can arrive more than once, including if your receiver processed it but its response was lost. Delivery order is not guaranteed. Deduplicate by the stable `X-Layarva-Event-Id`, **not** `X-Layarva-Delivery`, which changes between attempts.

Layarva accepts a 2xx response as success. Timeouts, connection failures and non-2xx responses can be retried, up to **six attempts in total**. Redirects are not followed. Keep the response body small, at most 4 KiB, and respond well within ten seconds. Do not intentionally return an error after you have durably accepted an event.

## Step 6: Inspect delivery history

With `webhooks.read`, send:

```http theme={null}
GET /webhooks?limit=25
GET /webhooks/YOUR_WEBHOOK_ID
GET /webhooks/YOUR_WEBHOOK_ID/deliveries?limit=25
```

Lists use `page.nextCursor`; send it as `after` for the next page. Delivery history contains event ID, status, attempt count, response status when available and a safe failure code. It does not expose your signing secret or receiver response body.

| Status | What it means |
| - | - |
| `PENDING` | Waiting for an attempt or retry |
| `SENDING` | An attempt is in progress |
| `DELIVERED` | Your receiver returned success |
| `FAILED` | Attempts ended without confirmed success |
| `CANCELLED` | Delivery access was withdrawn, for example by pausing or archiving |

Terminal history is retained for 30 days. `FAILED` cannot prove your receiver never saw the event: inspect its own durable processing record before repeating a business action.

## Step 7: Pause, resume or archive

With `webhooks.manage` and an Idempotency-Key:

* **Pause:** `PATCH /webhooks/{id}` with `{"enabled": false}`.
* **Resume:** `PATCH /webhooks/{id}` with `{"enabled": true}`.
* **Rename:** `PATCH /webhooks/{id}` with `{"name": "New name"}`.
* **Archive:** `DELETE /webhooks/{id}` with no body or `{}`.

Pause is not a replay buffer: queued deliveries may be cancelled, and events that occur while paused are not backfilled on resume. To change the URL, event selection or signing secret, archive the old subscription and create a new one.

The API key that created the subscription must remain valid and authorized. Revoking it, letting it expire or removing its permissions stops new delivery. Already transmitted requests cannot be recalled. If rotating that key, recreate the subscription with the replacement key before retiring the old integration.

## Troubleshooting

* **503:** feature unavailable; stop the workflow and contact support if it continues.
* **401/403:** check the Platform key, scopes, expiry and workspace access.
* **409 when creating:** archive an unused subscription before adding another. Paused subscriptions still count.
* **Signature rejected:** check secret, raw body handling and clock; do not reuse Queue webhook verification unchanged.
* **Repeated deliveries:** return 2xx promptly and deduplicate the stable event ID.
* **Delivery failed:** check your final HTTPS endpoint and receiver logs. Do not include secrets or full temporary URLs in a support request.

## Related guides

* [Platform API overview](https://docs.layarva.com/developers/platform-api.md)
* [Create Platform API keys](https://docs.layarva.com/developers/platform-api-keys.md)
* [Upload and verify files](https://docs.layarva.com/developers/platform-library.md)
* [Create and publish Ready Playlists](https://docs.layarva.com/developers/platform-playlists-publication.md)
* [Export offline packages](https://docs.layarva.com/developers/platform-offline.md)
* [Queue webhooks: a separate integration](https://docs.layarva.com/developers/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.