Webhooks

Webhook management is Plane B.

Subscribe

Create a subscription with:

Code
POST /internal/webhooks/subscriptions
X-Plug-Wallet-Api-Key: <api-key>

Use live outbound event patterns such as:

Code
["wallet.*", "kyc.approved", "kyc.rejected", "kyc.state.changed"]

wallet.* matches published wallet outbound events, including wallet.created. KYC outbound types are kyc.approved, kyc.rejected, and kyc.state.changed. kyc.verification.updated and contract.vault.recorded are not published webhook event types. Contract Vault recordings do not emit outbound webhooks.

Delivery safety

• Always verify webhook signatures.
• Respond quickly with a 2xx status.
• Make handlers idempotent.
• Store event IDs and ignore duplicates.
• Inspect one delivery with GET /internal/webhooks/deliveries/{id}.
• Replay one delivery with POST /internal/webhooks/deliveries/{id}/replay, or every delivery of a source event with POST /internal/webhooks/events/{eventId}/replay.

Event ownership

The webhook payload reports what happened. It is not the source of truth. Fetch the canonical resource from the API before making irreversible decisions.