Webhook Setup

To receive real-time webhook dispatches for payment authorizations, installment approvals, refunds, and disputes, register your public HTTPS listener endpoint with Amwal using the Webhook Registration API.

Registration Workflow

Unlike basic dashboard webhooks, Amwal provisions webhook endpoints programmatically alongside a dedicated verification keypair:

Rendering diagram...

Public Key Is Shown Only Once

When you register an endpoint via POST /api/create-webhook-and-apikey/, the response contains api_key.public_key in PEM format. Amwal does not show this key again. Store it securely in your environment variables as AMWAL_PUBLIC_KEY for use in Webhook Signature Verification.

Register Webhook Endpoint

Endpoint

POST /api/create-webhook-and-apikey/

Request Headers

Authorization: YOUR_SECRET_KEY
X-Amwal-Key: sandbox-amwal-xxx
Content-Type: application/json

Header	Type	Required	Description
`Authorization`	String	Yes	Your Amwal Secret API Key (e.g. `d9ccf8bc-ed63-44ad-a54c-9d8fee63df6b`).
`X-Amwal-Key`	String	No	Merchant publishable API Key or sandbox identifier.
`Content-Type`	String	Yes	Must be set to `application/json`.

Request Body

{
  "url": "https://api.yourdomain.com/webhooks/amwal",
  "description": "Production Webhook Receiver",
  "event_type_names": [
    "order.created",
    "order.success",
    "order.failed",
    "order.updated",
    "installment.tracker.approved",
    "installment.tracker.rejected",
    "order.disputed",
    "payment_link.expired",
    "modal.closed"
  ]
}

Request Parameters

Field	Type	Required	Description
`url`	String (HTTPS URI)	Yes	Your publicly reachable HTTPS webhook listener endpoint. Plain HTTP and self-signed certificates are rejected.
`description`	String	No	Optional human-readable description for audit tracking (e.g. `"Production Webhook Receiver"`).
`event_type_names`	Array of Strings	Yes	List of event types to subscribe to. See Webhook Event Types for all supported events.

Response (`201 Created`)

{
  "webhook_endpoint": {
    "id": "whk_9812401824",
    "url": "https://api.yourdomain.com/webhooks/amwal",
    "description": "Production Webhook Receiver",
    "event_type_names": [
      "order.created",
      "order.success",
      "order.failed",
      "order.updated",
      "installment.tracker.approved",
      "installment.tracker.rejected",
      "order.disputed",
      "payment_link.expired",
      "modal.closed"
    ]
  },
  "api_key": {
    "name": "Webhook API Key",
    "prefix": "amwal_pk_",
    "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0...\n-----END PUBLIC KEY-----"
  }
}

Response Parameters

Field	Type	Description
`webhook_endpoint.id`	String	Unique Amwal identifier for the registered webhook endpoint.
`webhook_endpoint.url`	String (URI)	The registered destination URL receiving webhook dispatches.
`webhook_endpoint.event_type_names`	Array of Strings	Active event subscriptions for this endpoint.
`api_key.prefix`	String	Identifier prefix for matching delivery headers.
`api_key.public_key`	String (PEM)	The RSA Public Key used to verify the `X-Signature` header on incoming dispatches. Save this key immediately.

cURL Example

curl -X POST https://backend.sa.amwal.tech/api/create-webhook-and-apikey/ \
  -H "Authorization: YOUR_SECRET_KEY" \
  -H "X-Amwal-Key: sandbox-amwal-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourdomain.com/webhooks/amwal",
    "description": "Primary Webhook Listener",
    "event_type_names": [
      "order.created",
      "order.success",
      "order.failed",
      "order.updated",
      "installment.tracker.approved",
      "installment.tracker.rejected",
      "order.disputed",
      "payment_link.expired",
      "modal.closed"
    ]
  }'

Testing Webhooks Locally

During development, your local server (e.g. http://localhost:3000) cannot receive external dispatches from Amwal's servers. Use ngrok or Cloudflare Tunnels to generate a secure HTTPS tunnel:

# 1. Start your local server
npm run dev

# 2. Expose local port 3000 to a public HTTPS tunnel
npx ngrok http 3000

Register the temporary ngrok HTTPS URL (https://xyz.ngrok-free.app/webhooks/amwal) using POST /api/create-webhook-and-apikey/ to test sandbox webhooks locally.