Webhooks

​

Getting started

​

Payload structure

{
  "event": {
    "id": "evt_1234567890",
    "type": "invoice.paid",
    "api_version": "2025-09",
    "created_at": "2025-01-15T10:30:00Z",
    "data": {
      "invoice": {
        // ... full invoice resource
      }
    }
  }
}

​

Headers

​

Signature verification

t={timestamp},v1={signature}

1. Extract the timestamp (t) and signature (v1) from the header
2. Reconstruct the signed payload: {timestamp}.{raw_request_body}
3. Compute the HMAC SHA256 using your endpoint’s secret key
4. Compare the computed signature with v1
5. Optionally, check the timestamp is recent to prevent replay attacks

def verify_webhook_signature(request_body, signature_header, secret)
  parts = signature_header.split(',').map { |p| p.split('=').last }
  timestamp = parts[0]
  signature = parts[1]

  signed_payload = "#{timestamp}.#{request_body}"
  computed = OpenSSL::HMAC.hexdigest('SHA256', secret, signed_payload)

  computed == signature
end

​

Retries

​

Best practices

• Implement idempotency — use event.id to ensure you don’t process the same event twice. Store processed event IDs and check before processing.
• Process asynchronously — for time-consuming operations, queue the webhook for background processing after returning a success response.
• Log the request ID — use X-Stora-Request-Id to correlate retry attempts when debugging.
• Validate signatures — always verify the HMAC signature before processing.
• Monitor your endpoint — extended downtime may exhaust all retry attempts.

​

Available events