Skip to main content
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.
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 for authenticated API requests. Paths below are relative to your workspace base URL. POST, PATCH and DELETE require a new Idempotency-Key for each new operation; reuse it only when retrying that same operation.
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:
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:
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

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:

Step 4: Verify each request before processing

Layarva sends a JSON POST to your receiver with these headers:
The signature is HMAC-SHA256 of:
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:
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:
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. 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.