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

# Testing guide

# Testing & Debugging Webhooks

Webhooks are asynchronous by nature, which can make testing them locally a challenge. Fype provides several tools to help you verify your webhook integration seamlessly.

## 1. Local Development with ngrok

Since Fype's servers need to reach your local development machine, you must use a tunneling service to expose your local port to the internet.

1. **Install ngrok**: Download and install [ngrok](https://ngrok.com/).
2. **Expose your port**: If your server is running on port `3000`, run:

```bash theme={null}
ngrok http 3000
```

3. **Update fype Dashboard**: Copy the `https` URL provided by ngrok (e.g., `https://random-id.ngrok-free.app`) and append your webhook path (e.g., `/webhooks/fype`). Add this as a **Test Mode** webhook endpoint in the Fype Dashboard.

## 2. The "Trigger Test Webhook" Tool

The Fype Dashboard includes a specialized tool to manually trigger simulated events. This allows you to test your listener without creating a real checkout session.

1. Go to **Developers > Webhooks**.
2. Ensure you have added a **Test Mode** endpoint.
3. Click the **Trigger Test Webhook** button.
4. Fype will immediately generate a `payment.succeeded` event for a dummy payment and enqueue it for delivery to your test endpoints.

## 3. Simulator Interactive Testing

When using a `fype_test_...` API key, the hosted checkout page renders an **Interactive Simulator**.

1. Initiate a payment and open the `checkout_url`.
2. In the simulator console, click **Simulate Success**.
3. Fype will process the mock payment and trigger a `payment.succeeded` webhook to your server.
4. You can also test error flows by clicking **Simulate Card Decline** (`payment.failed`) or **Simulate UPI Timeout**.

## 4. Auditing Delivery Logs

If you are not receiving webhooks, check the **Delivery Logs** in the Fype Dashboard:

* **Status Code**: View the exact HTTP response code your server returned (e.g., `200`, `404`, `500`).
* **Response Body**: See the first 2KB of your server's response. This is invaluable for debugging internal server errors.
* **Latency**: Check how long your server took to respond.
* **Retry History**: Fype retries failed deliveries up to 5 times. You can see the schedule and status of each attempt.

## 5. Common Issues

### Signature Verification Fails

* **Raw Body**: Ensure you are using the **raw** request body for HMAC verification. If your framework (like Express or NestJS) parses JSON automatically, you must retrieve the raw buffer before it is parsed.
* **Webhook Secret**: Verify that the `whsec_...` secret in your environment matches the one shown in the Fype Dashboard for that specific endpoint.

### 403 Forbidden

* **ngrok User Agent**: Some ngrok configurations block requests without a specific User-Agent. Fype uses `Fype-Webhooks/v1.0`.
* **IP Whitelisting**: Ensure your server is not blocking requests from external IPs.

### Webhooks arrive out of order

While rare, network latencies can cause webhooks to arrive out of sequence. Always check the `created_at` timestamp in the payload and use the `Payment` ID to perform idempotent updates.