Webhooks

Webhook Events

Sapiom can send webhook notifications when transaction events occur.

Setup

Configure webhook endpoints in your Sapiom Dashboard.

Event Types

• transaction.created - A new transaction was created
• transaction.authorized - A transaction was authorized
• transaction.declined - A transaction was declined
• transaction.completed - A transaction was completed
• transaction.failed - A transaction failed

Payload Format

{
  "event": "transaction.completed",
  "data": {
    "id": "txn_123abc",
    "status": "completed",
    "service": "openai",
    "action": "completion",
    "resource": "gpt-4",
    "createdAt": "2025-01-15T10:30:00Z",
    "completedAt": "2025-01-15T10:30:05Z"
  },
  "timestamp": "2025-01-15T10:30:05Z"
}

Verification

All webhook requests include a signature in the X-Sapiom-Signature header. Verify this signature to ensure the request is from Sapiom.

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}