Webhooks

Stabo pushes event notifications to your server through Webhooks (for example, when a payment is received). You learn about account changes in real time without polling.

Delivery mechanismCopy Anchor Link

• Protocol: HTTPS (TLS 1.2+)
• Method: HTTP POST
• URL: The Webhook URL that you configure in the Dashboard under Integrations → Webhooks (must use HTTPS)
• Content type: application/json
• Signature algorithm: HMAC-SHA256
• Retry policy: If the response status code is not 2xx, Stabo retries with exponential backoff, up to 5 times
• Retry intervals: 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours
• Timeout: 30 seconds (respond within 30 seconds)

Best practice: When you receive a Webhook notification, return a 2xx response first and process your business logic asynchronously. This prevents processing timeouts from causing duplicate deliveries.

Request headersCopy Anchor Link

Every Webhook request that Stabo sends includes the following HTTP headers:

Event objectCopy Anchor Link

{
  "id": "evt_1Mxxx",
  "object": "event",
  "type": "checkout.payment_intent.succeeded",
  "created": 1678888888,
  "data": {
    "object": {}
  }
}

Fields:

• id: Unique event identifier
• object: Fixed value "event"
• type: Event type (for example, checkout.payment_intent.succeeded)
• created: Event creation timestamp (seconds)
• data.object: Event payload (varies by event type)

For the event types and payloads of each product, see the product guide, for example Checkout Webhook events.

Signature verificationCopy Anchor Link

To make sure that a Webhook request comes from Stabo and is not forged by a third party, you must verify the signature of every request.

The format of Webhook-Signature is t=timestamp,v1=signature. To verify it:

1. Parse the header to get t (timestamp, in seconds) and v1 (signature).
2. Check the timestamp and reject expired requests. You choose the tolerance. The examples below use 300 seconds.
3. Build the signed payload: eventId + "." + timestamp + "." + rawBody. eventId comes from Webhook-Event-Id. rawBody is the raw, unparsed request body.
4. Compute HMAC-SHA256 of the signed payload with your Webhook secret, and encode the result as a lowercase hexadecimal string.
5. Compare the expected signature with v1 in constant time.

Verification code examplesCopy Anchor Link

# Variables from the request: EVENT_ID=Webhook-Event-Id, TIMESTAMP=t in Webhook-Signature
# RAW_BODY is the raw request body, WEBHOOK_SECRET is the Webhook secret
printf '%s' "${EVENT_ID}.${TIMESTAMP}.${RAW_BODY}" \
  | openssl dgst -sha256 -hmac "${WEBHOOK_SECRET}" \
  | sed 's/^.* //'

Test with a fixed sampleCopy Anchor Link

Use the sample below for self-testing. The secret is an example value. Pass the sample to any of the implementations above. The result must be true. When you verify, set the current time to within 300 seconds of t.

Raw request body (single line, no trailing newline):

{"id":"evt_1234567890","object":"event","type":"checkout.payment_intent.succeeded","created":1778480710,"data":{"object":{"paymentIntentId":"pi_MNOL0POUV8IDPXCD","status":"COMPLETED","amount":"20.00","currency":"USD","note":"测试 UTF-8"}}}

If you change any character in the request body, or change v1 to uppercase, verification must return false.