Skip to main content

Webhooks

Webhooks are event notifications that amser pushes to a merchant-configured HTTPS endpoint whenever authorization state changes or a payment occurs. Instead of polling the Indexer API, your server receives real-time signals the moment something happens on-chain.

Why Webhooks Matter​

On-chain events alone are not enough for most merchant integrations. When a subscription payment succeeds, you need to extend access. When a subscriber cancels, you need to update your database. When an allowance expires, you need to trigger a dunning email.

Webhooks close the gap between on-chain execution and server-side business logic. They enable merchants to:

  • Provision access immediately after a successful payment
  • Trigger dunning flows when payments fail or allowances expire
  • Update databases to reflect subscription state changes in real time
  • Sync revenue data with accounting and analytics systems

Limits​

Each merchant can register a maximum of 5 active webhook endpoints. To add a new endpoint when at the limit, delete an existing one first.

Architecture​

amser's webhook system has two components:

Webhook Endpoint​

This is your server — an HTTPS URL you register in the amser dashboard. When an event occurs, amser sends an HTTP POST request to this endpoint with a JSON payload describing the event. Your endpoint must respond with an HTTP 2xx status code to acknowledge receipt.

Retry Worker​

amser operates its own retry infrastructure. When a delivery fails (non-2xx response or timeout), a polling retry worker picks up the failed delivery and retries it on an exponential backoff schedule. This is not a third-party service — amser owns and operates this infrastructure directly.

Dispatch Model​

Events are dispatched in-process from the Indexer as it observes on-chain state changes. A separate polling retry worker handles failed deliveries independently. This design keeps the critical path fast (no external dependencies in the dispatch path) while ensuring reliability through the retry layer.

What's in This Section​

PageWhat You'll Learn
Events ReferenceEvery event type, with payload shapes and descriptions
Signature VerificationHow to verify that a webhook came from amser
Retry BehaviourRetry schedule, timeouts, and idempotency guidance

Next Steps​