Webhooks

A webhook endpoint is a URL of yours that ResellerHQ posts to when something happens. Deliveries follow the Standard Webhooks specification.

Add an endpointCopy Anchor Link

In the dashboard, open Developers and choose New endpoint. Or with the API:

curl -X POST https://resellerhq.com/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $RHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/resellerhq","events":["number.message.received"]}'

The response includes the endpoint's signing secret, which starts with whsec_. It is shown once. Use ["*"] to receive every event.

The URL must be https and must resolve to a public address.

EventsCopy Anchor Link

What you receiveCopy Anchor Link

{
  "id": "evt_01JABCDEF...",
  "type": "number.message.received",
  "timestamp": "2026-10-07T11:04:31.454Z",
  "data": {
    "messageId": "msg_01JABCDEF...",
    "rentalId": "num_01JABCDEF...",
    "number": "15550100002",
    "sender": "WhatsApp",
    "body": "Your code is 428-113",
    "receivedAt": "2026-10-07T11:04:31.000Z"
  }
}

Three headers come with it: webhook-id, webhook-timestamp and webhook-signature.

Example payloadsCopy Anchor Link

data's shape depends on the event. One worked example per event family, with the same field names the code that sends it uses:

Domain - domain.updated:

{ "id": "dom_01JABCDEF...", "domain": "northwind-mail.com", "changed": ["nameservers"] }

Mailbox domain - mailbox_domain.created:

{
  "id": "mdm_01JABCDEF...",
  "domain": "northwind-mail.com",
  "status": "propagating",
  "nameservers": ["ns1.resellerhq-dns.com", "ns2.resellerhq-dns.com"]
}

Mailbox - mailbox.active:

{
  "id": "mbx_01JABCDEF...",
  "email": "[email protected]",
  "mailboxDomainId": "mdm_01JABCDEF...",
  "domain": "northwind-mail.com"
}

mailbox.created and mailbox.failed carry the same four fields, plus status on mailbox.created and code and reason on mailbox.failed. See a mailbox order, end to end below for mailbox.setup_progress, which has a different shape.

Client ID - client_id.completed:

{
  "id": "cid_01JABCDEF...",
  "mailboxDomainId": "mdm_01JABCDEF...",
  "domain": "northwind-mail.com",
  "clientId": "102938475610293847561",
  "delegated": false
}

Licence - licence.created:

{ "id": "lic_01JABCDEF...", "plan": "google-workspace-starter", "domain": "northwind-mail.com", "seats": 5 }

Invoice / credit note - invoice.created:

{
  "id": "inv_01JABCDEF...",
  "number": "INV-00042",
  "customerId": "cus_01JABCDEF...",
  "currency": "USD",
  "total": 4200,
  "status": "open"
}

invoice.paid and invoice.voided carry the same fields, with status changed. credit_note.issued adds invoiceId, invoiceNumber, subtotal, tax, total and reason alongside its own id, number, customerId and currency.

Wallet - wallet.topped_up:

{ "topupId": "wtp_01JABCDEF...", "amount": 10000 }

Portal - portal.order.placed:

{
  "orderId": "pord_01JABCDEF...",
  "customerId": "cus_01JABCDEF...",
  "status": "placed",
  "invoiceId": "inv_01JABCDEF..."
}

Reseller / sub-reseller - subreseller.suspended:

{ "subResellerId": "rsl_01JABCDEF...", "reason": "Unpaid for 30 days" }

Price list / sale - price_list.updated:

{
  "id": "prl_01JABCDEF...",
  "name": "Wholesale",
  "changed": ["customerPrice"],
  "customers": 12,
  "customerIds": ["cus_01JABCDEF..."],
  "items": 37
}

The webhook payload example generator builds a sample envelope for any event type, and signs it with a secret you paste in.

A mailbox order, end to endCopy Anchor Link

Ordering several mailboxes on a domain you don't already hold sends a run of events, in this order - here, five mailboxes on a domain registered with us:

1. mailbox_domain.created
2. domain.updated, with changed: ["nameservers"], if the domain was registered with us (we point it at its mail nameservers ourselves)
3. mailbox.created × 5
4. mailbox_domain.active, once the domain's nameservers have propagated
5. mailbox.setup_progress, several times per mailbox, as each moves through Google's own setup steps
6. mailbox.active × 5, as each finishes

mailbox.setup_progress is frequent - several per mailbox - and purely informational: safe to ignore if all you want is mailbox.active or mailbox.failed. Its setupStage is an internal stage name from the mailbox provider, not a fixed list to match against, and the sandbox and live providers use different ones. In the sandbox, a mailbox walks scheduled, configuring_workspace, configuring_dns, configuring_dkim, configuring_auth and finalizing_setup on its way to active. Live, against Google Workspace, stages observed include seat while a mailbox is set up on its own, and domain_dns_zone, domain_verify and domain_customer while it waits on its shared domain. Treat any value you don't recognise the same way: informational, nothing to act on.

Verify the signatureCopy Anchor Link

Always verify before trusting a delivery. Any Standard Webhooks library does it:

import { Webhook } from 'standardwebhooks';

const webhook = new Webhook(process.env.RHQ_WEBHOOK_SECRET);

export async function POST(request: Request) {
  const body = await request.text(); // the raw body, not parsed JSON
  let event;
  try {
    event = webhook.verify(body, Object.fromEntries(request.headers));
  } catch {
    return new Response('bad signature', { status: 400 });
  }
  // handle the event
  return new Response(null, { status: 204 });
}

The signature is an HMAC-SHA256 over webhook-id.webhook-timestamp.body. Libraries also reject timestamps that are too old, which stops replays.

RetriesCopy Anchor Link

Answer with any 2xx within 10 seconds. Anything else is retried after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 14 hours, and then given up on - about 32 hours in all. An event is never dropped at that point: it is marked failed and can still be sent again, by you, whenever you are ready (see Resending a failed delivery below).

OrderingCopy Anchor Link

Deliveries about the same subject - a domain, a number, a mailbox, a licence, an order or an invoice - go out in the order the events happened, one at a time: the next one waits until the one before it has succeeded or finally failed, rather than racing ahead of it on a retry. Events about different subjects, or with no subject in common, are never held up by each other.

De-duplicationCopy Anchor Link

Because of retries, the same event can arrive more than once. webhook-id is the same each time, so store the ids you have handled and skip repeats. A delivery you resend from the dashboard or the API carries that same id too, so a receiver that already dedupes on it sees no difference from the original - resending is safe to do more than once.

Resending a failed deliveryCopy Anchor Link

A failed or blocked delivery can be sent again. In the dashboard, open Developers, find the endpoint under Webhook endpoints and choose View deliveries from its menu, then Resend on the delivery. Or with the API:

curl -X POST https://resellerhq.com/api/v1/webhook-deliveries/whd_01K6XJ4Q.../redeliver \
  -H "Authorization: Bearer $RHQ_API_KEY"

This queues a fresh delivery of the same event, ahead of anything else waiting for that endpoint and subject. The original delivery's own record is untouched; the new one gets its own id and its own retry schedule if it fails again.

Unhealthy and paused endpointsCopy Anchor Link

An endpoint whose deliveries have all failed for a day is marked unhealthy; after a week of nothing but failures it is paused, shown as a banner on its row in Developers. Pausing stops new deliveries being attempted - it does not stop them being made: events for a paused endpoint still queue, nothing is lost, and they start delivering again as soon as the endpoint answers successfully once more (including to a delivery you resend by hand).

In the API referenceCopy Anchor Link