DOCS / WEBHOOKS

Real-Time Event Notifications

Receive real-time push notifications when events occur in your SpendGuard account. Build reactive workflows with verified, reliable event delivery.

Register a Webhook Endpoint

create_webhook.ts

const webhook = await spendguard.webhooks.create({
  url: 'https://api.yourapp.com/webhooks/spendguard',
  events: [
    'payment.completed',
    'payment.failed',
    'mandate.violated',
    'agent.revoked'
  ],
  secret: 'whsec_your_secret_key'
});

Verify Webhook Signatures

Always verify the HMAC-SHA256 signature before processing events to ensure the request originated from SpendGuard.

verify_webhook.ts

app.post('/webhooks/spendguard', (req, res) => {
  const signature = req.headers['x-spendguard-signature'];
  const timestamp = req.headers['x-spendguard-timestamp'];

  const isValid = spendguard.webhooks.verify({
    payload: req.body,
    signature,
    timestamp,
    secret: 'whsec_your_secret_key'
  });

  if (!isValid) return res.status(401).send('Invalid signature');

  // Process the event
  const event = req.body;
  switch (event.type) {
    case 'payment.completed':
      handlePaymentCompleted(event.data); break;
    case 'mandate.violated':
      handleMandateViolation(event.data); break;
  }

  res.status(200).send('OK');
});

Reliable Retry Policy

Failed webhook deliveries are automatically retried with exponential backoff to ensure your systems stay in sync.

1st ATTEMPT

Immediate

2nd ATTEMPT

1 min

3rd ATTEMPT

5 min

4th ATTEMPT

30 min

5th ATTEMPT

2 hours

6th ATTEMPT

12 hours

Best Practices

Follow these guidelines to ensure a robust and secure webhook integration.

Always verify signatures before processing
Return 2xx response code immediately
Process heavier logic asynchronously
Handle duplicate events idempotently
Secure endpoints with HTTPS only

Start Building

Create your first webhook endpoint in the developer console to see live events in action.

Read API Spec