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 callPOST /inbound-email. Use them for mail forwarders deployed outside your control; anything else answers403.
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:
qmatches the subject, or the case number when it is a number such as42or#42.- Pass
nextCursorback ascursorto get the next page; it isnullon the last page. priorityis one oflow,normal,high,urgent.statuson/disputesis one ofneeds_response,under_review,won,lost,accepted,warning. Up to 100 disputes are returned.- The timeline from
/cases/:id/eventsincludes internal notes. - To reach out first, send
emailandmessage: the case opens on an email channel (taggedemailandoutbound) andmessageis emailed to the buyer, with the case number in the subject so their answer files on the same case.channelIdpicks the channel to send from and is required when the workspace has more than one enabled.event.data.deliveryissent, ornot_sentwith areason(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..." } }
}
transportis one of the transports the server offers (smtp,ses,cloudflare,cloudflare-binding,resend;ses,cloudflareandresendare 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 havenull.cloudflareis{ accountId, apiToken }for a domain on another Cloudflare account, only with transportcloudflare;nullremoves it. The token is never returned.resendis{ apiKey }, only with transportresend;sesis{ accessKeyId, secretAccessKey, region }, only with transportses.nullremoves them. Secrets are never returned; the channel showsresend: { hasKey: true }orses: { 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,resendorsesclearsverifieduntil the next successful check. ChangingsupportAddressto another domain starts over with a new ownership token. catchAllfiles mail to any address on the domain on this channel. It is on unless set tofalse.- Writes need a write key.
addressisnullwhen the server has noINBOUND_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 }
]
}
nameis the full record name andtypeisTXT,CNAMEorMX(withpriority). Records withoptional: trueare not needed to verify;purposemailfromrecords appear when the server setsAWS_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
409with amessage. 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>, wherev1is 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.