Receive real-time notifications when events happen in Alladdin.

⚡ Real-time 🔒 Signed payloads 🔄 Auto-retry 🎯 Event filtering

Overview

Webhooks allow you to receive HTTP POST notifications when events occur in your Alladdin account, such as a new invoice being created or a payment being received.

Setting up webhooks

Configure webhooks in your Alladdin dashboard under Settings > Webhooks. You'll need to provide:

• A publicly accessible HTTPS URL
• The events you want to subscribe to

Common headers

Every webhook request includes these headers:

x-alladdin-webhook-event string

Event name, e.g. invoice.create

x-alladdin-webhook-date string · ISO 8601

x-alladdin-webhook-signature string

HMAC-SHA256 signature with the sha256= prefix (see below)

x-alladdin-webhook-id string

Unique event identifier; use it as an idempotency key

x-alladdin-webhook-account-id string

Identifier of the Alladdin account that triggered the event

x-alladdin-webhook-version string

Webhook system version (e.g. v1)

Available events

Webhooks are available for the following event groups. Click a group to see its events and payload details.

Verifying webhooks

Each webhook request includes a signature header (x-alladdin-webhook-signature) that you should verify to confirm the request came from Alladdin. The signature is an HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret and prefixed with sha256=.

const crypto = require('crypto');

// Use the raw request body, not the parsed JSON object
app.post('/alladdin-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = process.env.ALLADDIN_WEBHOOK_SECRET; // whsec_... // The header arrives with a "sha256=" prefix; strip it before comparing const received = (req.header('x-alladdin-webhook-signature') || '').replace(/^sha256=/, '');

  const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');

  const valid = received.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
  if (!valid) return res.status(401).send('Invalid signature');

  const event = req.header('x-alladdin-webhook-event');
  const data = JSON.parse(req.body.toString('utf8'));

  // ... process the event and acknowledge
  res.sendStatus(200);
});

Expected response

Your endpoint should return any 2xx status code to acknowledge receipt. If we don't receive a 2xx response, we will retry the delivery with exponential backoff.