Webhooks

Use webhooks to receive real-time updates for receive, exchange, payout, refund, and statement events without polling the Verto API.

🛠️ Lifecycle Workflow

Set up your webhook flow in this order:

---

📂 Webhook Catalog

Verto emits events across every major module. Subscribe to the events that match your business logic.

🔵 Inward Liquidity (iban_to_wallet)

Triggered when external capital lands in a Verto vIBAN or Ledger account.

• Primary Use Case: Auto-funding user accounts in a Marketplace.
• Key Data: walletId, amount, reference, account (remitter details).

🔄 Currency Conversion (remittance_complete)

Triggered when an FX order executes successfully.

• Primary Use Case: Updating treasury balances post-swap.
• Event Types: outward_remittance_complete, inward_remittance_complete.

🔴 Outbound Payouts (wallet_to_account)

Triggered when funds successfully exit the Verto ecosystem.

• Primary Use Case: Sending "Payment Confirmed" notifications to end-users.

💰 Lifecycle Events

• Refunds: refund.completed
• Audit Logs: wallet.statement.generated

---

🧩 Handle webhook deliveries

Use this page as the high-level lifecycle guide, then use Webhook Event Handling for implementation examples and routing patterns.

At a minimum, your webhook consumer should:

1. receive the incoming POST request
2. identify the event type and payload
3. deduplicate the event before mutating internal state
4. route the event to the correct handler
5. return 200 OK within 5 seconds

---

🚦 Status Mappings

When processing webhook payloads, use the transactionState or status string to drive your internal business logic.

Send & Receive Data Mapping

Exchange Mapping

Sub-Account KYB Mapping

---

🔬 Atlas Payload Nuances

Depending on your integration path, the webhook payload might contain different identifying headers to help you route logic internally.

---

Handle review and RFI-related delays

Not every delayed webhook means a transaction failed. A payout, FX trade, beneficiary, receive flow, or onboarding workflow may be under review or waiting for a Request for Information (RFI).

If your system has not received a terminal webhook after your approved processing threshold:

1. Check the latest status through the relevant read endpoint.
2. Check whether the workflow is under review or waiting for additional information.
3. Move the item into an internal exception queue instead of retrying the original write request.
4. Notify your operations team or customer according to your RFI workflow.
5. Resume downstream processing only after the next status update or webhook confirms it is safe to continue.

Use Handle RFIs and Compliance Exceptions for the recommended exception state machine, customer messaging, and safe-retry rules.

---

🏆 Best Practices

⚖️

The Gold Rules of Webhooks

• Idempotency: Always check the id or eventId. Verto may deliver the same event multiple times if your ACK response is slow.
• Asynchronous Processing: Don't process long-running logic (like database writes) inside the webhook handler. Return 200 OK first, then queue the task.
• HTTPS Only: Verto will never send webhooks to a non-SSL (http://) URL.
• Acknowledge Quickly: Return a success response within 5 seconds so Verto does not treat the delivery as failed.
• Monitor Retries: Alert on repeated delivery failures and investigate handler errors before they affect reconciliation.

---

🎯 Next Steps

| Error Codes →
Handle failures gracefully. | Handle RFIs and Compliance Exceptions →
Route review-blocked workflows into an exception queue. |