Merchants register a webhook URL on-chain via set_merchant_webhook/get_merchant_webhook, but delivery happens off-chain. Document what the on-chain field is for, what an off-chain notifier must do, and how to make delivery reliable and secure.
Proposed steps:
- Create
docs/guides/webhooks.md.
- Document
set_merchant_webhook and get_merchant_webhook: authorization, URL format and length limits, and the event emitted on change.
- State clearly that the contract does not make HTTP calls: an off-chain service must watch events and deliver notifications.
- Specify a recommended webhook payload schema per event type (invoice created, paid, partially paid, refunded, voided, subscription charged, ticket purchased).
- Document delivery requirements: retries with backoff, idempotency keys derived from ledger sequence and event index, and at-least-once semantics.
- Document security: signing outbound webhooks, verifying signatures at the receiver, HTTPS-only, and not trusting the merchant-supplied URL (SSRF considerations for the notifier service).
- Include a reference notifier architecture diagram.
Acceptance criteria:
docs/guides/webhooks.md exists.- The on-chain/off-chain split is stated unambiguously.
- A concrete payload schema and retry/idempotency policy are specified.
- Webhook signing and SSRF risks are documented.
Merchants register a webhook URL on-chain via
set_merchant_webhook/get_merchant_webhook, but delivery happens off-chain. Document what the on-chain field is for, what an off-chain notifier must do, and how to make delivery reliable and secure.Proposed steps:
docs/guides/webhooks.md.set_merchant_webhookandget_merchant_webhook: authorization, URL format and length limits, and the event emitted on change.Acceptance criteria:
docs/guides/webhooks.mdexists.