Webhook Event State Transitions

Last updated: May 19, 2026

This article explains the different webhook event states and their transitions for bridge operations and Smart Deposit Addresses (SDAs).

SDA Webhook Events

SDAs support the following webhook events:

Event

Description

DEPOSIT_ADDRESS_CREATED

Emitted when a new SDA is successfully created

BRIDGE_ACCEPTED

Deposit detected; quote generated and bridge queued for execution

BRIDGE_EXECUTED

Withdrawal broadcast on destination chain; bridge complete

DEPOSIT_ADDRESS_BRIDGE_REJECTED

Bridge failed terminally (limits, AML, unsupported token, internal error)

DEPOSIT_ADDRESS_BRIDGE_DELAYED

Transient processing error; bridge will be retried

Note: BRIDGE_PENDING is defined in the API documentation but is not emitted for SDA flows, as quoting only happens after a deposit is received. BRIDGE_REFUNDED and BRIDGE_CANCELLED are also not sent for SDAs. DEPOSIT_ACCEPTED only occurs when using third-party swap providers and does not occur for SDAs.

Standard SDA Flow

BRIDGE_ACCEPTED → BRIDGE_EXECUTED  (normal, successful case)

Fast Deposit Detection Flow (select chains)

On chains where Rhino.fi supports fast deposit detection (processing begins before full block finality):

PENDING_CONFIRMATION → BRIDGE_ACCEPTED → BRIDGE_EXECUTED

PENDING_CONFIRMATION indicates the deposit was detected but Rhino.fi is waiting for additional block confirmations before processing. There are safeguards on individual transaction and rolling total amounts. Depending on traffic, some deposits may fall back to standard speed.

Error Flows

DEPOSIT_ADDRESS_BRIDGE_REJECTED              (terminal failure on first attempt)

DEPOSIT_ADDRESS_BRIDGE_DELAYED → DEPOSIT_ADDRESS_BRIDGE_REJECTED

                                              (retries exhausted)

DEPOSIT_ADDRESS_BRIDGE_DELAYED → BRIDGE_ACCEPTED → BRIDGE_EXECUTED

                                              (transient error resolved by retry)

Important: DEPOSIT_ADDRESS_BRIDGE_DELAYED cannot be followed by a client-initiated refund. Refunds from a delayed state are only possible if Rhino.fi determines the delay is unresolvable.

Manual Reprocessing After Rejection

In rare cases (e.g., AML false positives, temporary system issues), Rhino.fi may manually reprocess a REJECTED bridge after fixing the underlying cause. In this case:

DEPOSIT_ADDRESS_BRIDGE_REJECTED → BRIDGE_ACCEPTED → BRIDGE_EXECUTED

Critical: The id in the new BRIDGEACCEPTED event will be different from the id in the original DEPOSITADDRESS_BRIDGE_REJECTED event. Your system must be designed to handle ACCEPTED events arriving after a REJECTED event for the same deposit.

_id Field Semantics by Event Type

The meaning of the _id field differs across event types:

Event

_id represents

BRIDGE_ACCEPTED

Bridge ID (= commitment ID). Same value in EXECUTED.

BRIDGE_EXECUTED

Bridge ID — same as in ACCEPTED

DEPOSIT_ADDRESS_BRIDGE_REJECTED

Rejected SDA bridge record ID (not a bridge ID)

DEPOSIT_ADDRESS_BRIDGE_DELAYED

Delayed/failed record ID (not a bridge ID)

When a REJECTED bridge is reprocessed, the subsequent ACCEPTED event carries a new bridge ID — it will never match the original REJECTED record's _id.

Rejection Reason Codes

DEPOSIT_ADDRESS_BRIDGE_REJECTED events include a reason field with one of the following values:

Reason

Meaning

Refundable?

UNDER_MIN

Deposit below minimum limit

✅ Yes (if above $1)

OVER_MAX

Deposit above maximum limit

✅ Yes

UNSUPPORTED_TOKEN

Token not supported by the SDA or bridge

✅ Yes (ERC-20 tokens only; not NFTs)

OPERATION_UNAVAILABLE

AML block — cannot be disclosed until investigation closes

⚠ Case-by-case; may be seized

TERMINAL_PROCESSING_ISSUE

Internal processing error; very rare

✅ Refund or delayed execution

NO_ROUTE_FOUND

Currently unused; reserved for future routing features

—

Note: OPERATION_UNAVAILABLE is exclusively used for AML blocks. Rhino.fi is not permitted to inform clients about AML alerts during the investigation.

Correlating REJECTED Records with Reprocessed Bridges

If you need to link an original REJECTED record to a later reprocessed BRIDGE_ACCEPTED event, use one of the following fields:

  • txHash — deposit transaction hash on the source chain (primary correlation key)

  • addressNote — if set on the SDA at creation time, this is included in all webhook payloads (recommended approach: set to your internal user ID)

  • Recipient / destination address — if each SDA maps to a unique user

  • SDA address — if you issue one SDA per user

Webhook Delivery & Infrastructure

  • Rhino.fi's production webhook sender IP address: 34.78.119.255 — add this to your network allowlist if your environment is not publicly accessible.

  • There are currently no webhook events for refund completion. Refund status must be tracked via your shared Slack channel with Rhino.fi support.

  • Implement proper retry logic and idempotent event handling. Duplicate events are possible.

Implementation Checklist

  • ✅ Handle BRIDGE_ACCEPTED → BRIDGE_EXECUTED as the happy path

  • ✅ Handle PENDING_CONFIRMATION on supported chains before BRIDGE_ACCEPTED

  • ✅ Handle DEPOSIT_ADDRESS_BRIDGE_REJECTED as a (usually) terminal state

  • ✅ Be prepared for BRIDGE_ACCEPTED arriving after a prior REJECTED event (reprocessing)

  • ✅ Correlate events by txHash, addressNote, or destination address — not by _id across event types

  • ✅ Whitelist 34.78.119.255 if your webhook endpoint is behind a firewall

  • ✅ Implement idempotent webhook handlers (duplicate delivery is possible)