Skip to main content
The current Solana alert webhook events supersede the legacy ones. They change the delivery model from “one event per transaction” to “one event per address involved”, and introduce a new event type for delegated transfers along with new payload fields. This guide is for customers still consuming the legacy Solana alert webhook events who want to migrate.

​
What’s changing

  • Per-address delivery. The legacy webhook sent a single event per Solana transaction. The new webhook sends one event per subscribed address involved in the transaction. If two of your Portal clients are involved in a single Solana transaction (e.g. one sends SOL to the other), you will now receive two webhook events for that transaction — each with a different triggeredBy value and the same signature.
  • New event types. Each legacy event type has a replacement, plus a brand-new event for delegated transfers:
    • SOLANA_TX_V2 — Solana native (SOL) transfers and SPL token transfers. (Replaces SOLANA_TX_V1, without delegated transfers.)
    • SOLANA_APPROVE_V2 — Solana delegation approve transactions. (Replaces SOLANA_APPROVAL_V1.)
    • SOLANA_REVOKE_V2 — Solana delegation revoke transactions. (Replaces SOLANA_REVOKE_V1.)
    • SOLANA_DELEGATED_TRANSFER_V2 — New event. Fires when a delegate executes a transfer using funds from another user’s previously-approved delegation.
    If you don’t subscribe to SOLANA_DELEGATED_TRANSFER_V2, you will not be notified when a delegate moves tokens that one of your addresses had previously approved. To preserve parity with the legacy “every transfer involving my addresses” behavior, subscribe to both SOLANA_TX_V2 and SOLANA_DELEGATED_TRANSFER_V2.
  • triggeredBy field. Every event payload now includes a triggeredBy field. It identifies which of your subscribed addresses caused this specific event delivery. Use this to route events to the right user/account on your side without re-deriving it from the raw transaction data.
  • direction field. Every event payload also includes a direction field that describes what the triggeredBy address did in the transaction:
  • recentBlockhash field. Every event payload now includes a recentBlockhash field — the base58-encoded recentBlockhash of the transaction.

​
Payload differences

The same Solana transfer (a 0.01 SOL receive) shows up like this on the legacy webhook vs the new one. Note the new triggeredBy and direction fields, and the type value changing from SOLANA_TX_V1 to SOLANA_TX_V2.

​
Event payloads

Below is a full example payload for each new event type so you can wire up parsers and types ahead of cutting over.

​
SOLANA_TX_V2

​
SOLANA_APPROVE_V2

​
SOLANA_REVOKE_V2

​
SOLANA_DELEGATED_TRANSFER_V2

​
Migration steps

  1. Expect multiple events per transaction. If two or more of your subscribed addresses are involved in the same Solana transaction, you will receive one event per address. Update your event handlers to be safe under this fan-out.
    • Idempotency between transactions: dedupe on the signature field. Solana transactions are uniquely identified by their signature, so it works as a stable idempotency key for “have I seen this transaction before?”.
    • Idempotency per (transaction, address): dedupe on the composite key signature + triggeredBy. Use this when you process events per-address, so each (transaction, address) pair is processed exactly once even if the webhook is retried.
  2. Subscribe to the events you need from the Portal Admin Dashboard. In the Alert Webhooks settings, select the event types your integration cares about: SOLANA_TX_V2, SOLANA_APPROVE_V2, SOLANA_REVOKE_V2, and/or SOLANA_DELEGATED_TRANSFER_V2.
    If you want to keep parity with the legacy webhook — i.e. be notified about every transfer involving your addresses — subscribe to both SOLANA_TX_V2 and SOLANA_DELEGATED_TRANSFER_V2. Without SOLANA_DELEGATED_TRANSFER_V2, transfers executed by a delegate against an approval that one of your addresses granted will not generate any webhook event.
  3. Test that events are being received with the correct types. Send a test transaction (devnet works well) and confirm:
    • You receive an event whose type ends in _V2 (not _V1).
    • The payload contains both triggeredBy and direction.
    • When two of your subscribed addresses are involved in the same transaction, you receive two events with different triggeredBy values and a shared signature.