Webhooks

Quick start

1. Open Settings → Webhooks in the SalesThumb app.
2. Click New subscription.
3. Enter a label, your HTTPS URL, and pick the events you care about.
4. Save the signing secret — it's shown once.
5. Click Send test to verify your endpoint receives + verifies the request.

Payload envelope

Every event is wrapped in the same envelope. Thedata field varies by event type.

{
  "event": "invoice.paid",
  "shopId": "01234567-89ab-cdef-0123-456789abcdef",
  "timestamp": "2026-04-26T14:23:11.000Z",
  "data": {
    "invoiceId": "01234567-...",
    "customerId": "01234567-...",
    "totalCents": 84900,
    "paidAt": "2026-04-26T14:23:11.000Z"
  }
}Language: json

Headers on every request:

Content-Type: application/json
User-Agent: SalesThumb-Webhook/1.0
X-SalesThumb-Event: invoice.paid
X-SalesThumb-Signature: sha256=<hex digest>
X-SalesThumb-Delivery: <unique uuid per attempt>Language: text

Signature verification

Verify the signature before trusting a payload. The signature isHMAC-SHA256(secret, raw_body). Compare in constant time.

import crypto from "node:crypto";

export function verifyWebhook(secret, header, rawBody) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const provided = header.replace(/^sha256=/, "");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(provided, "hex"),
  );
}Language: javascript

import hmac, hashlib

def verify_webhook(secret: str, header: str, raw_body: bytes) -> bool:
    expected = hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    provided = header.replace("sha256=", "", 1)
    return hmac.compare_digest(expected, provided)Language: python

require "openssl"

def verify_webhook(secret, header, raw_body)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, raw_body)
  provided = header.sub(/^sha256=/, "")
  Rack::Utils.secure_compare(expected, provided)
endLanguage: ruby

Event catalog

All event types you can subscribe to. More are added as new modules ship — see /changelog for additions.

Retries & auto-disable

The platform considers any non-2xx response a failure. Failures are recorded but not retried automatically yet— this is on the immediate roadmap (exponential backoff over ~24h). For now, your endpoint should be idempotent and queue work internally if it can't process synchronously.

After 10 consecutive failures, the subscription is auto-disabledand you'll be notified by email. Re-enable it from the dashboard once you've fixed the endpoint.

Timeout: 10 seconds. Long-running work should ack the webhook quickly (return 200 immediately) and process asynchronously.

Best practices

• Verify X-SalesThumb-Signature on every request before trusting the payload.
• Treat X-SalesThumb-Delivery as an idempotency key — store it and skip duplicates.
• Return 2xx fast. Queue heavy work for an async worker.
• Subscribe to the narrowest set of events you need.
• Rotate the signing secret periodically (90 days is reasonable).

FAQ