> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unwall.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Real-time notifications for deposits and transfer events.

# 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.

<Info>
  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.
</Info>

## 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.xyz webhook signatures are verified using the `BRIDGE_WEBHOOK_PUBLIC_KEY` before any balance updates are applied.

## Error Handling

<AccordionGroup>
  <Accordion title="Signature verification failure">
    If the webhook signature is invalid, the endpoint returns `400 Bad Request` and logs the failure. The event is not processed.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Unknown event type">
    Unrecognized event types are logged and acknowledged with `200 OK` to prevent unnecessary retries.
  </Accordion>
</AccordionGroup>