Skip to main content
Monigo sends webhooks to your server when important events occur — invoice paid, payout completed, customer nearing their quota, etc.

​
Setting up a webhook endpoint

  1. Go to Dashboard → Webhooks → Add Endpoint
  2. Enter your HTTPS URL
  3. Select the event types you want to receive
  4. Copy the signing secret

​
Verifying webhook signatures

Every Monigo webhook includes a X-Monigo-Signature header. Verify it before processing the request. 
import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

// In your handler:
app.post('/webhooks/monigo', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-monigo-signature'] as string;
  if (!verifyWebhook(req.body.toString(), sig, process.env.MONIGO_WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  // handle event...
  res.status(200).send('ok');
});

​
Event types

EventDescription
invoice.createdNew invoice generated
invoice.paidInvoice payment succeeded
invoice.failedInvoice payment failed
invoice.voidedInvoice voided
payout.batch.submittedPayout batch sent to provider
payout.slip.paidIndividual payout transfer confirmed
payout.slip.failedIndividual payout transfer failed
customer.quota.warningCustomer at 80% of their usage cap
customer.quota.exceededCustomer reached their hard cap
subscription.createdNew subscription started
subscription.cancelledSubscription cancelled

​
Retries

If your endpoint returns a non-2xx status, Monigo retries up to 5 times with exponential backoff:
AttemptDelay
1st retry30 seconds
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry8 hours
After 5 failed attempts, the delivery is marked as failed and no further retries occur. You can manually retry from the dashboard.

​
Testing webhooks locally

Use the Monigo CLI to forward webhooks to your local server: 
monigo listen --forward http://localhost:3000/webhooks/monigo
Or use a tunnelling tool like ngrok and register the public URL in your dashboard.