Webhooks

Webhooks notify your server when events happen in your Salam account.

Setting Up Webhooks

1. Go to Dashboard → Developers → Webhooks
2. Click Add Endpoint
3. Enter your webhook URL
4. Select events to subscribe to
5. Copy the signing secret

Webhook Events

Event	Description
payment.created	Payment was created
payment.authorized	Payment was authorized
payment.captured	Payment was captured
payment.failed	Payment failed
payment.cancelled	Payment was cancelled
refund.created	Refund was initiated
refund.succeeded	Refund completed
refund.failed	Refund failed

Webhook Payload

{
  "id": "evt_abc123",
  "type": "payment.captured",
  "created_at": "2024-01-15T12:00:00Z",
  "data": {
    "id": "pay_xyz789",
    "amount": 10000,
    "currency": "MYR",
    "status": "captured",
    "payment_method": "fpx"
  }
}

Verifying Signatures

Always verify webhook signatures to ensure authenticity:

import Salam from '@salamgateway/node';

const salam = new Salam({
  apiKey: 'sk_live_xxx',
  webhookSecret: 'whsec_xxx',
});

app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['salam-signature'];
  
  try {
    const event = salam.webhooks.constructEvent(req.body, signature);
    
    switch (event.type) {
      case 'payment.captured':
        handlePaymentSuccess(event.data);
        break;
      case 'payment.failed':
        handlePaymentFailure(event.data);
        break;
    }
    
    res.json({ received: true });
  } catch (error) {
    console.error('Webhook verification failed:', error);
    res.status(400).send('Invalid signature');
  }
});

Best Practices

Important

• Return 200 quickly - Process asynchronously if needed
• Handle duplicates - Use idempotency keys
• Verify signatures - Never skip verification
• Use HTTPS - Required for production

Retry Policy

Failed webhooks are retried with exponential backoff:

• Retry 1: 5 minutes
• Retry 2: 30 minutes
• Retry 3: 2 hours
• Retry 4: 8 hours
• Retry 5: 24 hours

After 5 failed attempts, the webhook is marked as failed.

Testing Webhooks Locally

Use ngrok to test webhooks locally:

# Install ngrok
npm install -g ngrok

# Start your server
npm run dev

# Expose it
ngrok http 3000

# Use the URL: https://abc123.ngrok.io/webhooks/salam

Next Steps

• Error Handling - Handle webhook failures
• Going Live - Production checklist