Webhooks
Unwall receives webhooks from Bridge.xyz to process deposits and transfer status updates in real time. All webhook endpoints verify cryptographic signatures before processing any event.These are platform-internal webhooks (Bridge.xyz sends events to Unwall). Developer-facing webhooks — where Unwall notifies your application of events — are on the roadmap.
Bridge.xyz Events
Bridge.xyz webhooks handle USDC deposits and outgoing transfer status updates.| Event | Action |
|---|---|
deposit.confirmed | USDC deposit received on-chain. The project’s USDC balance is credited via a ledger posting. |
transfer.completed | Outgoing transfer (USDC or fiat off-ramp) settled successfully. Transaction status updated to completed. |
transfer.failed | Outgoing transfer failed. Transaction marked as failed and the amount is credited back to the project’s balance. |
BRIDGE_WEBHOOK_PUBLIC_KEY before any balance updates are applied.
Error Handling
Signature verification failure
Signature verification failure
If the webhook signature is invalid, the endpoint returns
400 Bad Request and logs the failure. The event is not processed.Processing failure
Processing failure
If an error occurs while processing a valid webhook, the endpoint returns
500 Internal Server Error. The payment provider retries the webhook according to its retry policy.Unknown event type
Unknown event type
Unrecognized event types are logged and acknowledged with
200 OK to prevent unnecessary retries.