> For the complete documentation index, see [llms.txt](https://hollow-peak.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hollow-peak.gitbook.io/docs/payments/webhooks.md).

# Webhooks

How providers confirm payments, and how to test them.

A webhook is the provider telling your site what happened, server to server. It is the **authority** on whether a payment succeeded.

## Why they matter

Without a working webhook, a payment can succeed at the provider while your order stays pending — the customer has paid and nothing has happened.

This is the single most common cause of “payment went through but the order did not”.

## Addresses

All webhooks use one pattern:

```
https://your-domain.com/webhooks/{provider}
```

| Provider | Address                                   |
| -------- | ----------------------------------------- |
| Stripe   | `https://your-domain.com/webhooks/stripe` |
| PayPal   | `https://your-domain.com/webhooks/paypal` |
| Manual   | Not applicable                            |

These addresses are deliberately outside session authentication — a provider has no session. Security comes from the signature instead.

## Verification

Every webhook is verified before anything changes:

* **Stripe** — HMAC signature against your signing secret
* **PayPal** — verified by sending the event back to PayPal with your Webhook ID

{% hint style="danger" %}
An unverified webhook is an unauthenticated request to mark an order paid. Hollow Peak rejects it outright, and there is deliberately **no setting** that relaxes this.

If webhooks are being rejected, the secret is wrong. Do not look for a way to disable the check.
{% endhint %}

## Replay and duplicates

Providers retry webhooks, sometimes for days, and may send the same event twice. Hollow Peak records which events it has processed, so a repeated event does not create a second payment or a second confirmation email.

## Testing before you are public

A provider cannot reach `localhost`. Use a tunnel.

**Stripe CLI** — the simplest option for Stripe:

```bash
stripe listen --forward-to localhost:8000/webhooks/stripe
```

It prints a signing secret for the session — paste that into Hollow Peak while testing.

```bash
stripe trigger checkout.session.completed
```

**ngrok** — works for any provider:

```bash
ngrok http 8000
```

Register the public `https://` address it prints with your provider.

## Checking they arrive

Every provider dashboard shows recent webhook deliveries with response codes.

| Response | Meaning                                       |
| -------- | --------------------------------------------- |
| **200**  | Received and processed                        |
| **400**  | Signature failed — wrong secret               |
| **404**  | Wrong URL, or the provider name is misspelled |
| **419**  | Should not happen; report it                  |
| **500**  | Server error — check `storage/logs`           |

## Common problems

**Signature verification fails.** The secret belongs to the other mode. Test and live webhooks have different secrets in both Stripe and PayPal.

**404.** Check the address is exactly `/webhooks/stripe`, not `/webhook/stripe`.

**Nothing arrives.** The provider cannot reach your server. Confirm the site is publicly accessible over HTTPS and no firewall blocks the provider.

**Order still pending despite 200.** The event type may not be subscribed. Check the list on the provider's page here.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://hollow-peak.gitbook.io/docs/payments/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
