API reference

Webhooks

Get notified when things happen. Register HTTPS endpoints and subscribe each to the events you care about (or '*' for all). Taxstar POSTs a signed JSON payload to your URL for every matching event. Requires an access token. Note: endpoint management is available now; event delivery is being rolled out by the Temporal layer.

How delivery works

For each event matching one of your subscriptions, Taxstar sends an HTTP POST to your url with a JSON body and an X-Taxstar-Signature header. Return a 2xx status to acknowledge; non-2xx responses are retried with back-off. Always verify the signature before trusting a payload.

Example event payload

{
  "id": "evt_...",
  "type": "invoice.delivered",
  "created_at": "2026-06-21T10:00:00Z",
  "data": {
    "invoice_id": "...",
    "invoice_number": "INV-1001",
    "status": "DELIVERED"
  }
}

Verifying the signature

// Node.js (Express) — verify an incoming Taxstar webhook
import crypto from "crypto";

function verify(req, signingSecret) {
  // header: "X-Taxstar-Signature: t=<unix_ts>,v1=<hex hmac-sha256>"
  const header = req.headers["x-taxstar-signature"] || "";
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("="))
  );
  const t = parts.t;
  const signed = `${t}.${req.rawBody}`; // raw, unparsed JSON body
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(signed)
    .digest("hex");
  // constant-time compare; optionally reject if |now - t| is too large
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1 || "")
  );
}

Delivery (signing, POST and retries) is performed by the Temporal layer and is being rolled out. Endpoint management below is available now.

GET/oauth/webhooks/event-typesAccess token

List event types

Return the event types you can subscribe to. Currently: invoice.sent, invoice.delivered, invoice.failed, invoice.received, invoice.status_changed. Use '*' to subscribe to all (including future) events.

POST/oauth/webhooksAccess token

Create a webhook

Register an endpoint. The response includes the signing_secret used to verify event signatures — it is shown in full only on create and rotate, so store it now.

Request body example

{
  "url": "https://example.com/taxstar/webhook",
  "events": [
    "invoice.sent",
    "invoice.delivered",
    "invoice.failed"
  ],
  "description": "Production invoice events",
  "is_active": true
}

Body parameters

`url`	string	required	HTTPS endpoint events are POSTed to. http(s):// required; https strongly recommended.
`events`	string[]	optional	Event types to subscribe to. Defaults to [""] (all events). Allowed: invoice.sent, invoice.delivered, invoice.failed, invoice.received, invoice.status_changed, or "".
`description`	string	optional	Free-text label to help you identify this endpoint.
`is_active`	boolean	optional	Whether the endpoint is enabled. Defaults to true.

GET/oauth/webhooksAccess token

List webhooks

List the webhook endpoints registered by your application. The signing_secret is masked here (a hint only) — fetch a single webhook to reveal it.

Query parameters

`page`	Page number. Defaults to 1.
`limit`	Page size, 1–100. Defaults to 20.

GET/oauth/webhooks/{webhook_id}Access token

Get a webhook

Fetch a single webhook, including its full signing_secret (so you can configure signature verification on your receiver).

Path parameters

webhook_id The webhook id returned on create.

PATCH/oauth/webhooks/{webhook_id}Access token

Update a webhook

Update a webhook's url, subscribed events, description, or active state. Only the fields you send are changed.

Path parameters

webhook_id The webhook id.

Request body example

{
  "events": [
    "*"
  ],
  "is_active": false
}

Body parameters

`url`	string	optional	New HTTPS endpoint. http(s):// required.
`events`	string[]	optional	New subscription list. Allowed: invoice.sent, invoice.delivered, invoice.failed, invoice.received, invoice.status_changed, or "*".
`description`	string	optional	New label.
`is_active`	boolean	optional	Enable (true) or pause (false) deliveries.

POST/oauth/webhooks/{webhook_id}/rotate-secretAccess token

Rotate signing secret

Issue a new signing_secret and return it once. The previous secret stops working immediately — update your receiver before rotating.

Path parameters

webhook_id The webhook id.

DELETE/oauth/webhooks/{webhook_id}Access token

Delete a webhook

Permanently stop deliveries to this endpoint.

Path parameters

webhook_id The webhook id.

PreviousInvoices