Skip to content

Webhooks

Spendware webhooks deliver signed event payloads to subscriber endpoints. Use webhooks when your application needs to react to Spendware events without polling.

Delivery Semantics

  • Delivery is asynchronous.
  • Delivery is at least once.
  • Global ordering is not guaranteed.
  • Non-2xx responses and transport failures are retried until attempt limits are exhausted.
  • Subscribers should deduplicate by event ID or delivery ID.

Payload Envelope

Webhook payloads include:

  • id.
  • type.
  • created_at.
  • tenant_id.
  • data.

Signature Verification

Webhook requests include signature and trace headers:

  • X-Spendware-Signature.
  • X-Spendware-Timestamp.
  • X-Spendware-Delivery-Id.
  • X-Spendware-Webhook-Signature.
  • X-Spendware-Webhook-Event.
  • X-Spendware-Webhook-Delivery.

The signature base string is:

{timestamp}.{delivery_id}.{raw_body}

Verify against the raw request body, reject stale timestamps, compare signatures with constant-time comparison, and return 2xx only after durable subscriber-side processing.

Endpoint Secrets

Create and rotate responses show the full endpoint signing secret once. Store it immediately and never log it.