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.manageto create, pause or archive a subscription, andwebhooks.readto 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.
Step 1: Generate and save the signing secret
Generate it once on your own computer or backend using Node.js:_ 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:
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:- 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. - Call the helper with the three headers and your saved signing secret. Reject an invalid signature or timestamp without processing the event.
- Parse the verified JSON. Check that
workspaceIdis your workspace and bodyidmatchesX-Layarva-Event-Id. - Save the event durably with a unique constraint on its event ID. An already-saved ID is a duplicate, not a new action.
- Return a small 2xx response promptly, including for an already accepted duplicate. Process longer-running work asynchronously from your saved event.
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 stableX-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
Withwebhooks.read, send:
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
Withwebhooks.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{}.
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.

