Skip to main content

​
What are Webhooks?

Webhooks are HTTP callbacks that FossaPay sends to your server when events occur. They enable real-time notifications about payments, payouts, and other important events.

​
Webhook Structure

All webhooks follow this format: 
{
  "event": "deposit.completed",
  "event_id": "evt_abc123",
  "timestamp": "2024-01-15T10:30:45Z",
  "data": {
    // Event-specific data
  },
  "business_id": "bus_your_business"
}

​
Configuration

​
Set Webhook URL

curl -X PUT https://api-staging.fossapay.com/api/v1/settings/webhooks \
  -H "Authorization: Bearer fp_live_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/fossapay",
    "events": [
      "deposit.completed",
      "withdrawal.completed",
      "transfer.completed",
      "transfer.failed",
      "wallet.balance.updated"
    ],
    "secret": "your-webhook-secret"
  }'

​
Verifying Signatures

Always verify webhook signatures: 
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return hash === signature;
}

app.post('/webhooks/fossapay', (req, res) => {
  const signature = req.headers['x-fossapay-signature'];

  if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  res.status(200).send('OK');
  processWebhook(req.body);
});

​
Best Practices

Return 200 status immediately, process asynchronously
Always verify the signature before processing
Use event_id to detect duplicate deliveries
FossaPay retries failed webhooks up to 5 times

​
Testing

Use ngrok for local testing: 
ngrok http 3000
Then set the ngrok URL as your webhook endpoint in the dashboard.

​
Next Steps

Webhook Events

View all available webhook events

Webhooks Concept

Learn more about webhooks