Webhooks

Receive real-time HTTP notifications when events happen in your Wyrr account. Webhooks eliminate the need to poll the API for changes.

Delivery Guarantees

At-least-once delivery with automatic retries
Events include an idempotency-safe id field
Events are signed with HMAC-SHA256 for verification
Failed deliveries retained for 72 hours

Retry Behavior

If your endpoint returns a non-2xx status code or times out (30s), Wyrr retries with exponential backoff:

Retry 1

1 minute

Retry 2

5 minutes

Retry 3

25 minutes

Retry 4

2 hours

Retry 5

24 hours

Verifying Signatures

Every webhook request includes a Wyrr-Signature header. Verify it using your endpoint secret to ensure the request came from Wyrr.

webhook-handler.js

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

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

// In your webhook handler:
app.post('/webhooks/wyrr', (req, res) => {
  const signature = req.headers['wyrr-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WYRR_WEBHOOK_SECRET
  );

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

  // Process the event
  const event = req.body;
  switch (event.type) {
    case 'payment.succeeded':
      // Fulfill the order
      break;
    case 'payment.failed':
      // Notify the customer
      break;
  }

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

Event Types

payment.*

Triggered by payment lifecycle events.

payout.*

Triggered by payout lifecycle events.

dispute.*

Triggered by dispute and chargeback events.

customer.*

Triggered by customer lifecycle events.

balance.*

Triggered when account balances change.

kyc.*

Triggered by KYC/KYB verification events.