Webhooks

Receive notifications when a transaction is approved.

Overview

• Trigger: Transaction status changes to APPROVED
• Method: POST to your configured URL
• Retry: 3 attempts with exponential backoff (5s, 10s, 15s)
• Response: Return 2xx status code

Webhook Request

Headers

Payload

{
  "event": "transaction.approved",
  "timestamp": "2024-12-08T10:30:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "vendorReference": "ORDER-2024-001",
    "orderReference": "AB12345",
    "status": "APPROVED",
    "amount": 500.00,
    "currency": "MAD",
    "customerPhone": "212612345678",
    "merchantName": "My Store",
    "storeName": "Downtown Branch",
    "createdAt": "2024-12-08T10:25:00Z"
  }
}

Signature Verification

The signature is computed as:

signature = HMAC-SHA256(webhookSecret, timestamp + "." + payload)

Header format: X-Alya-Signature: sha256={hex_signature}

Handling Webhooks

1. Verify signature - Always validate the signature
2. Return 200 quickly - Acknowledge receipt immediately
3. Process asynchronously - Handle business logic after responding
4. Check for duplicates - Use X-Alya-Event-Id to prevent duplicate processing
5. Validate timestamp - Reject webhooks older than 5 minutes

Event Types

Best Practices

• Use HTTPS for webhook URLs
• Return 2xx status code within 10 seconds
• Store X-Alya-Event-Id to prevent duplicate processing
• Implement idempotent handlers
• Verify signature on every webhook