How Webhooks Work

This guide provides a detailed explanation of how webhooks work in Fatoorah Pay, including the complete flow, delivery mechanism, and best practices.

Complete Webhook Flow

┌─────────────┐
│   Customer  │
│  Completes  │
│   Payment   │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│  Fatoorah Pay   │
│  Processes      │
│  Payment        │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Webhook Event   │
│  Triggered       │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Calculate HMAC  │
│  Signature       │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  HTTP POST to    │
│  Your Server     │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Your Server     │
│  Receives &      │
│  Verifies        │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Process        │
│  Payment Update │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Return 200 OK  │
└─────────────────┘

Step-by-Step Process

Step 1: Payment Initiated

Customer initiates payment through:

Payment link (shared URL)
Payment intention (integrated checkout)

// Create payment with webhook URL
const payment = await createPaymentLink({
  amount_cents: 10000,
  notification_url: 'https://your-server.com/webhooks/payment'
});

Step 2: Customer Completes Payment

Customer enters payment details and completes the payment:

Card information
3D Secure authentication (if required)
Payment confirmation

Step 3: Fatoorah Pay Processes Payment

Fatoorah Pay processes the payment:

Validates payment details
Processes through payment gateway
Updates payment status
Records transaction

Step 4: Webhook Event Triggered

When payment status changes, a webhook event is triggered:

Events:

payment.succeeded - Payment completed successfully
payment.failed - Payment failed or was declined

Step 5: HMAC Signature Calculated

Fatoorah Pay calculates HMAC-SHA256 signature:

// Pseudo-code
const payload = JSON.stringify(webhookData);
const signature = hmacSha256(payload, webhookSecret);

The signature is included in the X-Fatoorah-Signature header.

Step 6: HTTP POST Sent to Your Server

Fatoorah Pay sends HTTP POST request to your notification_url:

Request Headers:

POST /webhooks/payment HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Fatoorah-Signature: sha256=abc123...
User-Agent: FatoorahPay-Webhook/1.0

Request Body:

{
  "event": "payment.succeeded",
  "intention_id": "660e8400-e29b-41d4-a716-446655440001",
  "payment_link_id": null,
  "status": "PAID",
  "amount_cents": 10000,
  "currency": "SAR",
  "transaction_id": "FT-K7X9M2P4Q1",
  "paid_at": "2025-12-04T10:05:00+03:00",
  "display_id": "PI-X4Y6Z9A1B3"
}

Step 7: Your Server Receives Webhook

Your webhook endpoint receives the request:

app.post('/webhooks/payment', (req, res) => {
  const signature = req.headers['x-fatoorah-signature'];
  const payload = req.body;
  
  // Verify signature (Step 8)
  // Process webhook (Step 9)
  // Return response (Step 10)
});

Step 8: Signature Verification

Your server verifies the HMAC signature:

const isValid = verifySignature(payload, signature, webhookSecret);
if (!isValid) {
  return res.status(401).send('Invalid signature');
}

See Webhook Verification for detailed verification code.

Step 9: Process Payment Update

Your server processes the payment update:

if (payload.event === 'payment.succeeded') {
  // Update order status
  await updateOrderStatus(payload.intention_id, 'PAID');
  
  // Fulfill order
  await fulfillOrder(payload.intention_id);
  
  // Send confirmation email
  await sendConfirmationEmail(payload.intention_id);
}

Step 10: Return 200 OK

Your server must return HTTP 200 OK:

res.status(200).send('OK');

Important: Return 200 OK even if you encounter errors processing the webhook. Log errors internally and handle them separately.

Step 11: Retry Mechanism (If Needed)

If your server doesn't return 200 OK, Fatoorah Pay retries:

Attempt	Delay	Total Time
1	Immediate	0 minutes
2	1 minute	1 minute
3	5 minutes	6 minutes
4	30 minutes	36 minutes
5	2 hours	2 hours 36 minutes
6	24 hours	26 hours 36 minutes

Webhook Delivery Timeline

When Webhooks are Sent

Webhooks are sent immediately after payment status changes:

Payment Succeeded: Sent as soon as payment is confirmed
Payment Failed: Sent when payment fails or is declined

Delivery Order

Webhooks are delivered in the order events occur:

Payment initiated → (no webhook)
Payment processing → (no webhook)
Payment succeeded → payment.succeeded webhook
Payment failed → payment.failed webhook

Idempotency Handling

The same webhook may be delivered multiple times due to:

Retry mechanism
Network issues
Server restarts

Always make your webhook handler idempotent:

// Check if already processed
const webhookId = `${payload.event}-${payload.intention_id}`;
if (await isProcessed(webhookId)) {
  return res.status(200).send('OK'); // Already processed
}

// Process webhook
await processPayment(payload);

// Mark as processed
await markProcessed(webhookId);

res.status(200).send('OK');

Webhook Payload Structure

Common Fields

All webhook payloads include:

event - Event type (e.g., "payment.succeeded")
intention_id - Payment intention UUID (if applicable)
payment_link_id - Payment link UUID (if applicable)
status - Payment status (PAID, FAILED, etc.)
amount_cents - Payment amount in cents
currency - Currency code (e.g., "SAR")
transaction_id - Transaction display ID (e.g., "FT-XXXXXXXXXX")
paid_at - Payment completion timestamp (ISO 8601, null if not paid)
display_id - Payment intention/link display ID

Field Ordering

Fields are ordered consistently for HMAC verification. Always verify signatures using the exact payload as received.

Request Headers

X-Fatoorah-Signature

HMAC-SHA256 signature of the request body:

X-Fatoorah-Signature: sha256=abc123def456...

Format: sha256=<hex_signature>

Content-Type

Always application/json:

Content-Type: application/json

User-Agent

Identifies Fatoorah Pay webhook client:

User-Agent: FatoorahPay-Webhook/1.0

Response Requirements

HTTP Status Codes

Status Code	Meaning	Retry Behavior
200	Success	No retry
4xx	Client Error	Retry with exponential backoff
5xx	Server Error	Retry with exponential backoff
Timeout	No response	Retry with exponential backoff

Response Time

Your endpoint must respond within 30 seconds. Responses taking longer will timeout and trigger retries.

Response Body

Response body is optional but recommended:

// Minimal
res.status(200).send('OK');

// With confirmation
res.status(200).json({ received: true });

Retry Behavior

Retry Conditions

Webhooks are retried if:

Non-200 Response:
- 4xx status codes (client errors)
- 5xx status codes (server errors)
Timeout:
- No response within 30 seconds
Network Errors:
- Connection refused
- DNS resolution failure
- SSL/TLS errors

Retry Schedule

Retries use exponential backoff:

Attempt 1: Immediate
Attempt 2: +1 minute
Attempt 3: +5 minutes
Attempt 4: +30 minutes
Attempt 5: +2 hours
Attempt 6: +24 hours

Maximum Retries

After 5 retry attempts (6 total including initial), the webhook is marked as FAILED and no further retries are attempted.

Handling Retries

Your endpoint should handle duplicate webhooks gracefully:

// Idempotent webhook handler
app.post('/webhooks/payment', async (req, res) => {
  const { event, intention_id } = req.body;
  
  // Check if already processed
  const processed = await db.webhooks.findOne({
    event,
    intention_id,
    processed: true
  });
  
  if (processed) {
    // Already processed, return OK
    return res.status(200).send('OK');
  }
  
  // Process webhook
  try {
    await processPayment(req.body);
    
    // Mark as processed
    await db.webhooks.create({
      event,
      intention_id,
      processed: true,
      processed_at: new Date()
    });
    
    res.status(200).send('OK');
  } catch (error) {
    // Log error but still return 200
    console.error('Webhook processing error:', error);
    res.status(200).send('OK');
  }
});

Best Practices

Verify Signatures Always - Never trust unverified webhooks
Return 200 OK Quickly - Process webhooks asynchronously if needed
Handle Duplicates - Make your endpoint idempotent
Log Everything - Keep detailed logs for debugging
Monitor Failures - Set up alerts for webhook delivery issues
Test Thoroughly - Test with ngrok before production
Respond Quickly - Keep processing time under 30 seconds

Troubleshooting

Webhook Not Received

Possible Causes:

Webhook URL not publicly accessible
Firewall blocking incoming connections
Server not running
Incorrect URL in request

Solutions:

Use ngrok for local testing
Check firewall rules
Verify server is running
Double-check webhook URL

Webhook Received Multiple Times

This is normal! Webhooks may be delivered multiple times due to retries.

Solution: Make your endpoint idempotent (check if already processed).

Webhook Signature Invalid

Possible Causes:

Incorrect webhook secret
Request body modified before verification
Signature verification logic incorrect

Solutions:

Verify webhook secret is correct
Don't modify request body before verification
Check signature verification code

Next Steps

Webhook Setup - Initial webhook configuration
Webhook Events - Available events and payloads
Webhook Verification - HMAC signature verification