REST API and webhooks

Read and write cases with workspace API keys, and receive signed webhook deliveries when cases, messages and disputes change.

Authentication

Create a key in the console under API and webhooks. Keys belong to one workspace and are shown once. Creating keys and webhooks needs the “Rename the workspace” permission, which admins have.

  • Read keys list and read cases, timelines, disputes and email channels.
  • Write keys can also open cases, add internal notes, change case status, manage email channels and deliver inbound email.
  • Deliver email only keys (inbound) can only call POST /inbound-email. Use them for mail forwarders deployed outside your control; anything else answers 403.

Send the key on every request:

Authorization: Bearer rdk_...

A missing, wrong or revoked key gets 401. A read key trying to write gets 403. Cases from other workspaces answer 404.

Base URL: https://<your Rebutdesk host>/api/v1.

Endpoints

Method Path Body or query Returns
GET /cases status, tag, q, cursor, limit (1 to 200, default 50) { items, nextCursor }, newest activity first
GET /cases/:id { case, contact }
GET /cases/:id/events { items }, the timeline in order
POST /cases { subject, body?, email?, name?, priority?, tags?, message?, channelId? } { case } (201). With email, the buyer is found or created. With message too, { case, event }: see below
POST /cases/:id/notes { body } { event } (201)
POST /cases/:id/status { status: "open" | "pending" | "resolved" | "closed" } { case }
GET /disputes status { items }, those waiting for a response first
GET /channels/email { items }, the workspace’s email channels
POST /channels/email { supportAddress, transport?, cloudflare?, resend?, ses?, name?, fromName?, catchAll? } { channel } (201), or the existing channel with that support address (200)
GET /channels/email/:id { channel }
PATCH /channels/email/:id { name?, enabled?, fromName?, supportAddress?, transport?, cloudflare?, resend?, ses?, catchAll? } { channel }
DELETE /channels/email/:id { ok: true }. Its cases stay
GET /channels/email/:id/domain Checks the sending domain once; see below
POST /inbound-email ?to=&from=, raw RFC 822 body See Inbound email

Details:

  • q matches the subject, or the case number when it is a number such as 42 or #42.
  • Pass nextCursor back as cursor to get the next page; it is null on the last page.
  • priority is one of low, normal, high, urgent.
  • status on /disputes is one of needs_response, under_review, won, lost, accepted, warning. Up to 100 disputes are returned.
  • The timeline from /cases/:id/events includes internal notes.
  • To reach out first, send email and message: the case opens on an email channel (tagged email and outbound) and message is emailed to the buyer, with the case number in the subject so their answer files on the same case. channelId picks the channel to send from and is required when the workspace has more than one enabled. event.data.delivery is sent, or not_sent with a reason (for example, the support address is not verified yet); the case is kept either way.
  • Allowed status changes: open to pending, resolved or closed; pending to open, resolved or closed; resolved to open or closed; closed to open. Anything else answers 409.

Errors are JSON: { "error": "<code>", "message": "<what went wrong>" }. Invalid input answers 400 with invalid, a missing case 404 with not_found, a conflict 409 with conflict.

Example:

curl -X POST https://app.rebutdesk.com/api/v1/cases \
  -H "Authorization: Bearer $REBUTDESK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Order #1042: wrong size","email":"maya@example.com","tags":["shopify"]}'

Email channels

A channel object:

{
  "id": "01a1...",
  "name": "help@shop.example",
  "enabled": true,
  "fromName": "Shop Support",
  "supportAddress": "help@shop.example",
  "catchAll": true,
  "address": "shop-k3x9@in.example.com",
  "sendingDomain": { "domain": "shop.example", "transport": "cloudflare", "verified": false, "verifiedAt": null, "cloudflare": { "accountId": "0123..." } }
}
  • transport is one of the transports the server offers (smtp, ses, cloudflare, cloudflare-binding, resend; ses, cloudflare and resend are always offered for a domain’s own account), and is required with a new support address on servers that offer them. See Email. Channels from before the server offered a choice have null.
  • cloudflare is { accountId, apiToken } for a domain on another Cloudflare account, only with transport cloudflare; null removes it. The token is never returned.
  • resend is { apiKey }, only with transport resend; ses is { accessKeyId, secretAccessKey, region }, only with transport ses. null removes them. Secrets are never returned; the channel shows resend: { hasKey: true } or ses: { accessKeyId, region }.
  • New credentials are tried against their provider before they are saved; a wrong key answers 400 with the provider’s message.
  • Changing transport, cloudflare, resend or ses clears verified until the next successful check. Changing supportAddress to another domain starts over with a new ownership token.
  • catchAll files mail to any address on the domain on this channel. It is on unless set to false.
  • Writes need a write key. address is null when the server has no INBOUND_EMAIL_DOMAIN.

GET /channels/email/:id/domain checks the DNS records once and answers:

{
  "domain": "shop.example",
  "address": "help@shop.example",
  "transport": "ses",
  "verified": false,
  "records": [
    { "type": "TXT", "name": "_rebutdesk.shop.example", "value": "rebutdesk-verify=...", "purpose": "ownership", "ok": false },
    { "type": "CNAME", "name": "abc._domainkey.shop.example", "value": "abc.dkim.amazonses.com", "purpose": "sending", "ok": false },
    { "type": "TXT", "name": "_dmarc.shop.example", "value": "v=DMARC1; p=none", "purpose": "dmarc", "ok": false, "optional": true }
  ]
}
  • name is the full record name and type is TXT, CNAME or MX (with priority). Records with optional: true are not needed to verify; purpose mailfrom records appear when the server sets AWS_SES_MAIL_FROM_SUBDOMAIN.
  • Values do not change between calls, so records you have written stay valid. Polling once a minute is fine.
  • When the provider cannot check the domain, it answers 409 with a message. For a domain on its own Cloudflare account, the message includes Cloudflare’s error, such as an invalid token.
  • When another workspace proves the same domain later, it takes the domain over.

Inbound email

POST /inbound-email?to=<envelope recipient>&from=<envelope sender> with the raw message (RFC 822) as the body files mail on this workspace’s channels. to is required. It matches the channel’s forwarding address, its support address, or any address on its domain unless catchAll is false; the domain does not need to be verified. Needs a write or inbound key.

Answer Meaning
202 {"ok":true} Filed, or ignored on purpose (duplicate or automated mail).
422 {"error":"rejected","reason":"..."} Rejected, for example Unknown mailbox for an address that is not this workspace’s. Bounce it to the sender.
413 Over 25 MB.
400 Empty body or no to.
5xx Try again later.

Webhooks

Under API and webhooks, Webhooks, enter an Endpoint URL (public https only), tick events (none ticked sends every event) and click Add endpoint. The signing secret is shown once. URLs with a user name or password, and local or private addresses, are refused.

Each delivery is a POST with a JSON body:

{
  "id": "01a1...",
  "type": "message.created",
  "created_at": "2026-10-28T10:06:41.000Z",
  "workspace_id": "01a1...",
  "case": { "id": "01a1...", "number": 3, "subject": "Order #1042: wrong size", "status": "open" },
  "data": { "event_id": "01a1...", "actor_type": "contact", "actor_id": "...", "body": "Hi, ..." }
}

Events: case.created, case.status_changed, case.assigned, message.created, note.created, dispute.opened, dispute.updated, dispute.evidence_submitted, refund.created, commitment.created, commitment.overdue, and ping from Send test. A ping has case set to null.

Headers:

  • Rebutdesk-Event: the event type.
  • Rebutdesk-Delivery: unique per delivery; retries reuse it, so you can drop duplicates.
  • Rebutdesk-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body> with your endpoint’s signing secret (the same scheme as Stripe).

Check the signature before trusting a delivery:

import crypto from "node:crypto";

function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex"));
  const given = Buffer.from(parts.v1 ?? "");
  return given.length === expected.length && crypto.timingSafeEqual(expected, given);
}

timingSafeEqual throws when the two buffers differ in length, hence the length check first.

Deliveries are sent right after the change that caused them. Answer with any 2xx within 10 seconds. Redirects are not followed. Anything else, or no answer, is retried after 1, 4, 9 and 16 minutes, then given up. Retries run from the background job, which runs every minute.

Each endpoint shows its last delivery and has Send test, Recent deliveries (with states such as Delivered, Retrying and Gave up), Pause and Resume, and Delete. A paused endpoint receives nothing.

Self-hosted servers can set WEBHOOK_ALLOW_HTTP=true to allow http and local addresses while developing.