Skip to content
Praxical Store
Integrate

Receive & verify webhooks

Signed events, durable retries, secret rotation and receiver deduplication.

Connect a receiver

Receivers must resolve exclusively to public addresses. Redirects, private networks and URL credentials are rejected. There can be five enabled and ten saved receivers per app. Delivery also checks that the managing owner and publisher organization remain active.

  1. Open an app workspace, then Webhooks & license codes. As an active publisher owner, add a receiver name, public HTTPS URL and selected event types.
  2. Save the whsec_ signing secret immediately in the receiver’s secret storage. The store shows it only after creation or rotation.
  3. Implement raw-body signature verification and durable event deduplication. Send a test event from the workspace and inspect its delivery history.
  4. Return a 2xx response after the event is durably accepted into your own processing queue. Keep expensive work outside the HTTP request.

Verify exact bytes

Praxical follows the Standard Webhooks HMAC-SHA256 signing format. Read webhook-id, webhook-timestamp and webhook-signature. Base64-decode the secret after removing whsec_. Sign webhook-id + '.' + webhook-timestamp + '.' + the exact raw request body; compare against a v1,<base64> entry in the space-separated signature header in constant time.

Require a canonical integer timestamp within five minutes of your clock, then verify before parsing or acting on JSON. Do not reserialize the body. The body contains id, type, timestamp, api_version, product_id and event-specific data; it excludes customer email addresses, raw codes and credentials.

The offline publisherctl command verifies the signature and time window. Your receiver must still durably deduplicate webhook-id and verify that the body’s product_id is the app it expects.

Verify exact bytes examplebash
publisherctl webhook-verify \
  -secret-file receiver.secret \
  -payload event.json \
  -id '<webhook-id>' \
  -timestamp '<webhook-timestamp>' \
  -signatures '<webhook-signature>'

Delivery and retries

Delivery is at least once, and arrival order is not guaranteed. The event ID and body remain stable across automatic retries and manual replay; each HTTP attempt receives a current timestamp and signature. Keep processed event IDs for at least the seven-day delivery lifetime, and make downstream effects idempotent.

Requests time out after ten seconds. 2xx is accepted. HTTP 410 disables the receiver. Redirects and other 4xx responses fail permanently, except 408 and 429, which retry; network failures and 5xx responses also retry. Automatic delivery allows eight attempts per cycle with bounded exponential delays. The workspace can replay eligible history up to 24 total attempts within the delivery lifetime.

Delivery history and sanitized attempt results are kept for 30 days. Remote response bodies are not stored. Pausing, removing or changing a receiver cancels affected queued deliveries; an in-flight request can still arrive. Use the authoritative API when an event requires current state.

Rotate without a gap

Choose an overlap of one or 24 hours while deploying a new receiver secret. During overlap, the sender includes signatures from both keys. A second overlapping rotation is rejected until the first overlap ends; immediate rotation revokes both earlier keys. Update your receiver before the overlap expires.

Events cover release validation/publication/withdrawal/scheduling, listing publication, payment confirmation, refund decisions, gift redemption and publisher license batch activity. A refund approval event is a workflow decision, not proof that a provider refund completed. The API reference and receiver event picker enumerate the implemented types.

Protocol reference: Standard Webhooks specification.