Register a Relay tenant and receive lifecycle webhooks

A wrapper product gets one pairing prefix, one server key, and one webhook URL. Typing the public code in TabWorker Relay does not register anything. The tenant was already set up.

Server only: Relay, the phone app, and the signed-in tab never see the webhook URL or the wrapper key. Those stay on your trusted server and on TabWorker Core.

Production admission and user authorization

Initial integration work focuses on 1Matic and J3. Production access requires manual approval. Apply for your integration before registration and scoped testing. Credentials identify your application; they do not authorize customer tabs.

The admission review covers publisher identity, demonstrated behavior, requested access, data recipients, and stop/revocation behavior. Expanding access or changing data recipients needs review. Selector maintenance within the same integration scope does not require uploading your proprietary recipes to Core. Application-wide suspension and isolation must be validated before broader partner onboarding; registration alone is not a safety certification.

Apply for production access

Complete the Relay developer application form. Submissions are emailed to team@tabworker.com for manual approval. Sending a form does not register a tenant, issue credentials, or authorize customer tabs.

The form asks for your legal operator and contacts, application and privacy URLs, intended work and access, actual data recipients, retention and deletion, human access, authorization controls, and a synthetic demo. It includes acknowledgments covering Limited Use, training restrictions, processor handling, scope changes and credential protection. Do not include secrets or customer data.

TabWorker reviews the application and demonstration before deciding whether to issue production access. Keep each claim supported by evidence; an acknowledgment does not establish that a control works. Any approved application still needs the customer's separate browser grant. Your planner and proprietary recipes remain on your server.

The optional hitl.* protocol event names below refer to customer confirmation or intervention during an application task.

Do this once

Ask TabWorker for a unique prefix (1–8 characters) and a wrapper key. The key is hashed at rest and shown raw only at issue time.
From your server, call PUT https://api.tabworker.com/api/v1/relay-tab/tenant with that key. Send webhookUrl, webhookSecret, and the WebSocket URL of your own brain (1GS).
Mint jobs with POST /api/v1/relay-tab/jobs using the same key and the same prefix. A key bound to prefix 1M cannot mint a J3 code.

GET /api/v1/relay-tab/tenant returns the stored prefix and webhook URL. It does not return the secret.

What the customer types

The customer types one public code in Relay. Core looks up the full code, returns the stored brain URL and token, and emits pairing.redeemed to your webhook if you subscribed. No extra registration happens at that moment.

Event cycle

Your brain reports tab work to Core. Core signs the payload and POSTs it to your webhook. Other wrappers never receive your events.

Event	Who emits it	When
`pairing.created`	Core	You minted a job and public code.
`pairing.redeemed`	Core	Relay successfully redeemed that code.
`automation.started`	Your brain	Before the first automated action.
`automation.progress`	Your brain	Optional, while filling a form.
`automation.error`	Your brain	The machine path halted.
`automation.ended`	Your brain	The machine path finished (draft filled, form filled).
`hitl.requested`	Your brain	A human must sign in, submit, or otherwise confirm.
`hitl.error`	Your brain	That human step failed or timed out.
`hitl.ended`	Your brain	The human step finished. Include the resulting URL when you have one.

Report events with POST /api/v1/relay-tab/jobs/<jobId>/events. For a listing product, hitl.ended data.url is the live listing. For an apply product, it is the confirmation page after submit.

Verify deliveries

Each POST to your webhook includes x-internal-timestamp, x-internal-event, and x-internal-signature (v1= plus hex HMAC-SHA256 of timestamp.eventType.rawBody). Use verifyTabWorkerWebhookSignature from the TypeScript SDK. Persist id and ignore duplicates.

POST /v1/tabworker/webhooks
x-internal-event: hitl.ended
x-internal-timestamp: 1700000000000
x-internal-signature: v1=…

{
  "id": "evt_job_…_hitl_ended_…",
  "type": "hitl.ended",
  "occurredAt": "2026-09-02T00:00:00.000Z",
  "prefix": "1M",
  "jobId": "job_…",
  "data": {
    "url": "https://example.com/listing/123",
    "marketplace": "craigslist",
    "status": "published",
    "runId": "run_…"
  }
}

Erase Core history for one customer

POST /api/v1/relay-tab/jobs/<jobId>/revoke stops future access. It does not delete Core snapshots, webhook payloads, or evidence.

On account deletion, call POST https://api.tabworker.com/api/v1/relay-tab/customer/purge with the exact externalRef used when minting jobs. Core erases every matching job for this tenant. A content-free job-id fence remains so a late writer cannot restore deleted content. Missing jobs return success. If runtime storage cannot be cleared, the response is 503 and the call is safe to retry; content is fenced and redacted first.

A single job may be erased with POST /api/v1/relay-tab/jobs/<jobId>/purge and the same externalRef. The wrong owner receives 404.

A Relay installation can be shared by more than one customer of the same tenant. POST /api/v1/relay-tab/associations/<associationId>/purge deletes that installation record only when no jobs remain linked.

This API does not delete records already delivered to your webhook or brain, and it does not establish deletion of backups or logs.

Two products, one Relay

The same Relay install can redeem more than one prefix. Each prefix has its own brain URL and webhook. Events do not cross prefixes. Put recipes on your brain, not on TabWorker Core.