Introduction
What Webhook does and how the pieces fit together.
Webhook tells your application when a Stellar Testnet wallet is paid. You register a wallet with the conditions a payment must meet and a URL on your server. When a payment arrives, Webhook checks it against those conditions and sends a signed HTTP request to your URL.
It is non-custodial: Webhook only reads the ledger. It never holds a secret key and cannot move funds.
The three things you create
| Thing | What it is |
|---|---|
| Endpoint | A URL on your server that receives webhooks, with its own signing secret. |
| Watch | A wallet address plus rules: which assets, what amount, which memo, which senders. Each watch delivers to one endpoint. |
| API key | How your server authenticates to the REST API. Starts with whk_test_. |
What happens to a payment
- A ledger closes on testnet, about every 5 seconds.
- Webhook sees every transfer to a watched wallet, whatever the asset.
- Each watch on that wallet evaluates the payment. The result is
VERIFIEDorREJECTED, with every reason it failed. - A verified payment creates one
payment.receivedevent. A rejected one createspayment.rejectedonly if the watch asked for it. - The event is signed and sent to the watch's endpoint. If your server does not answer with a
2xx, it is retried for up to two days.
A payment normally reaches your server 5 to 10 seconds after the ledger closes.