Webhooks Integration

Webhooks let your application receive real-time notifications when events occur in your Streamline account. Instead of polling, your endpoint receives HTTP POST requests with event payloads.

Setting up a webhook endpoint

Configure your endpoint URL in the dashboard under Settings → Webhooks. Your endpoint must:

// Example webhook endpoint (Node.js/Express)
app.post('/webhooks/streamline', (req, res) => {
  const signature = req.headers['x-streamline-signature'];
  const isValid = verifySignature(req.body, signature);
  
  if (!isValid) return res.status(401).send('Invalid signature');
  
  const event = req.body;
  console.log('Received event:', event.type);
  
  res.status(200).send('OK');
});
Debug context for dev

Event types

Your webhook will receive the following event types:

user.created
user.updated
user.deleted
subscription.started
subscription.renewed
subscription.cancelled
payment.succeeded
payment.failed

Payload structure

All webhook events follow this structure:

{
  "id": "evt_1a2b3c4d5e6f",
  "type": "user.created",
  "created": 1704067200,
  "data": {
    "object": "user",
    "id": "usr_9x8y7z",
    "email": "alex@example.com",
    "created": 1704067200
  }
}

Verifying signatures

Each webhook includes an HMAC signature in the X-Streamline-Signature header. Verify it using your webhook signing secret from the dashboard:

const crypto = require('crypto');

function verifySignature(payload, signature) {
  const secret = process.env.STREAMLINE_WEBHOOK_SECRET;
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return hash === signature;
}
Security best practice: Always verify the signature before processing the event. This prevents attackers from sending fake webhooks to your endpoint.

Retry behavior

If your endpoint does not return 200 OK, Streamline will retry delivery up to 3 times with exponential backoff (1 min, 10 min, 1 hour). After all retries fail, the webhook is marked as failed and you'll receive an email notification.

You can view failed webhooks and manually retry them in the dashboard under Activity → Webhooks.