> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gowasl.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Wasl Cards API Webhooks: Overview, Setup, and Security

> Understand how Wasl pushes real-time order and delivery events to your server via HTTP POST webhooks, and how to verify them securely.

Wasl uses webhooks to push event-driven notifications directly to your server so that your Wasl can react to order and delivery changes without polling. Whenever a key event occurs — such as a driver picking up an order, busy mode being activated, or a delivery being completed — Wasl sendsWasl an HTTP POST request containing a JSON payload to the webhook URL you have registered in your account settings.

You do not call webhook endpoints yourself. Instead, you expose a URL on your own infrastructure, register it with Wasl, and Wasl calls it on your behalf as events occur.

## Security Verification

Every webhook payload includes a `webhook_token` field. When you receive a webhook, you should compare this token against the secret value you configured in your Wasl account. Reject any request where the token does not match — this protects you against spoofed or replayed webhook calls from third parties.

<Warning>
  Never process a webhook payload without first validating that the `webhook_token` matches your configured secret. Skipping this check could allow malicious actors to inject fake events into your system.
</Warning>

## Responding to Webhooks

<Tip>
  Your webhook endpoint must respond with an **HTTP 200** status code to acknowledge successful receipt. Wasl interprets any non-200 response — or a connection timeout — as a delivery failure and may retry the request.
</Tip>

All webhooks are delivered as:

```
POST your-registered-webhook-url
Content-Type: application/json
```

Keep your handler lightweight. Acknowledge the webhook immediately with a 200 response, then process the payload asynchronously if heavier work is needed.

## Webhook Event Types

Wasl sends four categories of webhook events to your registered endpoint:

| Event | Description |
| - | - |
| **Status Update** | Fired whenever an order's delivery status changes. Includes driver location and tracking links. |
| **Busy Mode** | Fired when Wasl activates or revokes busy mode. During busy mode, new orders are not accepted. |
| **Post-Order Creation** | Fired after an order is successfully created. Includes estimated delivery and pickup times. |
| **Order Update** | Fired after order completion with the final delivery fee and distance. |

<CardGroup cols={2}>
  <Card title="Status Update" icon="map-pin" href="/api-reference/webhooks/status-update">
    Order delivery status changes, driver location, and tracking links.
  </Card>

  <Card title="Busy Mode" icon="clock" href="/api-reference/webhooks/busy-mode">
    Activation and revocation of busy mode — pause order submissions while active.
  </Card>

  <Card title="Post-Order Creation" icon="circle-check" href="/api-reference/webhooks/post-order-creation">
    Delivery info and estimated times sent immediately after order creation.
  </Card>

  <Card title="Order Update" icon="rotate" href="/api-reference/webhooks/order-update">
    Final delivery fee and distance sent after order completion.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.