Webhook integration

CORE CONCEPTS

Webhooks

Receive notifications from Sobtra and keep your application's billing records and customer access in sync.

What are webhooks?

Webhooks notify your server when an event occurs in Sobtra. Instead of repeatedly checking for changes, your application receives an HTTP POST request at a URL you register.

Use these notifications to update your application's billing records and respond to changes that affect customer access. Your application decides how billing and subscription states translate into access to your product.

Set up your endpoint

  • Create a publicly reachable endpoint in your application that accepts HTTP POST requests.
  • Register its URL with Sobtra and select the events you want to receive.
  • Choose the endpoint's environment: test or live. Specify test explicitly when testing; new endpoints default to live if no environment is supplied.
  • Save the signing secret returned when the endpoint is created.
  • Verify incoming requests before processing their contents.

Example receiver URL

textExample
https://your-application.com/webhooks/sobtra

Use HTTPS for your receiver and register the final destination URL. Sobtra does not follow redirects. Localhost and private network addresses are not suitable receiver destinations.

Which notifications will you receive?

Sobtra sends an event to active endpoints belonging to your merchant and matching the event's environment. An endpoint receives only event types explicitly included in its selected events.

Select the supported events relevant to your integration. You can update the endpoint URL, description, selected events, and environment, or disable the endpoint when you no longer want deliveries.

Request format

Each delivery is a JSON request with the following structure. The fields inside data depend on the event type.

Payload structure

typescriptExample
type SobtraWebhook = {
  id: string;
  type: string;
  createdAt: string;
  data: Record<string, unknown>;
};
  • id: the delivery identifier. It remains the same when Sobtra retries that delivery.
  • type: the event type used to select the appropriate handler.
  • createdAt: the ISO timestamp generated for this delivery attempt. It changes on retries.
  • data: the event-specific payload.

Request headers

httpExample
Content-Type: application/json
X-Sobtra-Event: <event-type>
X-Sobtra-Delivery: <delivery-id>
X-Sobtra-Timestamp: <unix-timestamp-in-seconds>
X-Sobtra-Signature: sha256=<hex-signature>

The environment is not a separate field in the shared payload envelope. Associate each receiver with its configured environment and use the matching Sobtra API key when retrieving related resources.

Verify the signature

Sobtra signs every request using HMAC-SHA256 and your endpoint's signing secret. Verify the signature against the exact raw request body before parsing or processing the event.

Signed content

textExample
signedContent = timestamp + "." + rawRequestBody
signature = HMAC-SHA256(endpointSecret, signedContent)

X-Sobtra-Signature: sha256=<signature-as-hex>

Use the complete signing secret, including its whsec_ prefix. Do not parse and reserialize the JSON before verification: even a whitespace change produces a different signature.

Node.js signature verification

typescriptExample
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifySobtraWebhook({
  rawBody,
  timestamp,
  signature,
  secret,
  toleranceSeconds = 300,
}: {
  rawBody: Buffer;
  timestamp: string | undefined;
  signature: string | undefined;
  secret: string;
  toleranceSeconds?: number;
}): boolean {
  if (
    !secret ||
    !timestamp ||
    !/^\d+$/.test(timestamp) ||
    !signature ||
    !/^sha256=[a-f0-9]{64}$/.test(signature)
  ) {
    return false;
  }

  const signedAt = Number(timestamp);
  const now = Math.floor(Date.now() / 1000);

  if (
    !Number.isSafeInteger(signedAt) ||
    Math.abs(now - signedAt) > toleranceSeconds
  ) {
    return false;
  }

  const expected = createHmac("sha256", secret)
    .update(timestamp + ".")
    .update(rawBody)
    .digest();

  const received = Buffer.from(
    signature.slice("sha256=".length),
    "hex",
  );

  return (
    received.length === expected.length &&
    timingSafeEqual(received, expected)
  );
}

The example uses a recommended five-minute timestamp tolerance to limit replay attempts. Keep your server clock synchronized. Sobtra generates a new timestamp and signature for each retry, so verify each incoming attempt independently.

Acknowledge deliveries

Sobtra treats any HTTP 2xx response as a successful delivery. Requests have a 10-second timeout. Keep your response small and acknowledge promptly after securely accepting the event.

  • Verify the signature and validate the event structure.
  • Check whether the delivery has already been accepted.
  • Durably store or enqueue new work before returning success.
  • Return a 2xx response for an already accepted duplicate.
  • Perform slower processing in a background worker.

Retries and failures

Sobtra makes up to five attempts per delivery: the initial attempt and up to four retries. Retry delays are approximately one minute, five minutes, fifteen minutes, and one hour after the preceding failed attempt. Actual delivery can occur later.

  • HTTP 2xx: the delivery succeeds and is not retried.
  • HTTP 429 or 5xx: Sobtra schedules another attempt while attempts remain.
  • Other HTTP 4xx responses: the delivery fails without an automatic retry.
  • Network errors and timeouts: Sobtra schedules another attempt while attempts remain.
  • HTTP redirects: Sobtra does not follow them; the delivery attempt fails and is eligible for retry.
  • After the fifth unsuccessful attempt, automatic retries stop.

If your application cannot durably accept an otherwise valid event, return a server error so the delivery remains eligible for retry. Monitor your receiver and reconcile billing records through the Integration API when necessary.

Duplicates and event ordering

Your receiver must tolerate repeated deliveries. For example, your server may accept an event successfully but its response may not reach Sobtra before the request times out.

  • Use the signed payload's id to deduplicate retries of the same delivery.
  • Make duplicate checks and event acceptance atomic so concurrent requests cannot enqueue the same work twice.
  • Keep business operations safe to repeat: the same underlying change can reach multiple registered endpoints with different delivery IDs.
  • Do not use createdAt to determine the original order of business events; it represents the delivery attempt.
  • Retrieve current resource state when a delayed notification could overwrite a newer local state.

Rotate your signing secret

Rotate an endpoint's secret if it has been exposed or your security policy requires a replacement. Save the newly returned secret and update your receiver promptly.

Subsequent delivery attempts, including retries, use the endpoint's current secret. Coordinate the change with your receiver: deliveries signed before rotation may still be in flight.

Before going live

  • Register a public HTTPS receiver using its final URL.
  • Select the events and environment your integration needs.
  • Store the signing secret securely and verify raw request bodies.
  • Test invalid signatures, duplicate deliveries, and temporary receiver failures.
  • Return a 2xx response within 10 seconds after durable acceptance.
  • Keep test events isolated from production records and access.
  • Monitor processing failures and reconcile current state when needed.

Related documentation