Webhooks Setup Guide

Webhooks are the recommended way to receive results instead of polling.

Step 1: Create an Endpoint

Create a POST endpoint on your server:

typescript

// Express.js example
app.post('/banan0-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-banan0-signature'];
  const payload = req.body.toString();
  
  if (!verifySignature(payload, signature)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  console.log('Received:', event.event, event.data.run_id);
  
  res.status(200).send('OK');
});

Step 2: Register the Webhook

bash

curl -X POST \
  -H "Authorization: Bearer bnn_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com/banan0-webhook"}' \
  "https://banan0.com/api/v1/webhooks"

Step 3: Store the Signing Secret

The response includes a signing_secret. Store it securely!

Step 4: Verify Signatures

typescript

import crypto from 'crypto';

const WEBHOOK_SECRET = process.env.BANAN0_WEBHOOK_SECRET;

function verifySignature(payload: string, signature: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry Behavior

Failed deliveries are retried 3 times

Exponential backoff between retries