Webhooks & Push

MAGMA delivers asynchronous events two ways:

Web Push to your client — subscribe a browser / app to receive notifications (resolutions, payouts, mission completions, and more) without polling the feed.
Inbound webhooks to the backend — the Helius NFT webhooks let MAGMA react to on-chain tier-NFT transfers. These are server-to-server and not something a client subscribes to, but integrators reselling or indexing tier NFTs should know how they behave.

All paths are relative to:

https://api.magmaprotocol.xyz

Method badges: GET POST PUT AUTH (credential or secret required).

Notifications system is building

The notification pipeline is under construction — endpoints are wired but the feed is still being populated end-to-end. The push subscription flow and types below are stable to build against; expect the volume of live events to grow as the backend ships. The read/feed endpoints live under Notifications.

Web Push subscription

Web Push uses the standard VAPID flow: fetch the server's public key, create a PushSubscription in the client with that key, then register the subscription with MAGMA. Notifications are then pushed to that subscription.

1. Get the VAPID public key

GET /v1/notifications/push/vapid-public-key

Returns the application server's VAPID public key. Pass it as applicationServerKey when you call pushManager.subscribe().

curl 'https://api.magmaprotocol.xyz/v1/notifications/push/vapid-public-key'

{ "vapid_public_key": "BPm…base64url…" }

2. Create the subscription in the client

const reg = await navigator.serviceWorker.ready;
const sub = await reg.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: vapidPublicKey, // from step 1
});

3. Register the subscription with MAGMA

POST /v1/notifications/push/subscribe

Send the wallet and the browser PushSubscription (endpoint + p256dh / auth keys) so the backend can deliver pushes to it.

Body field	Type	Description
`wallet`	string	Wallet the subscription belongs to.
`subscription`	object	The browser `PushSubscription` (`endpoint`, `keys.p256dh`, `keys.auth`).

{
  "wallet": "7xKX…9fПb",
  "subscription": {
    "endpoint": "https://fcm.googleapis.com/fcm/send/…",
    "keys": { "p256dh": "BPm…", "auth": "k9…" }
  }
}

Per-type preferences

A wallet can opt in or out of individual notification types.

GET /v1/notifications/push/preferences/:wallet

Read the wallet's current per-type push preferences.

PUT /v1/notifications/push/preferences/:wallet

Update them — send the map of notification types to a boolean enabled flag.

{ "narrative_resolved_true": true, "system_announcement": false }

VAPID keys are environment-bound

The VAPID key pair is provisioned per environment. If the public key from …/vapid-public-key changes, existing subscriptions must be re-created against the new key.

Notification types

There are 19 notification types. Use them to filter the feed, build preference toggles, and route client-side rendering.

Type	Fires when
`narrative_resolved_true`	A narrative you're involved in resolves TRUE.
`narrative_resolved_false`	A narrative you're involved in resolves FALSE.
`payout_received`	A payout lands in your wallet.
`new_backer_on_my_narrative`	Someone backs a narrative you created.
`creator_royalty_paid`	A creator royalty is paid to you.
`mission_completed`	You complete a mission.
`streak_milestone`	Your backing streak hits a milestone.
`streak_broken`	Your streak is broken.
`echo_pool_epoch_ended`	An Echo Pool epoch closes.
`challenge_opened`	A challenge opens.
`challenge_resolved`	A challenge resolves.
`conviction_tier_up`	Your Conviction tier increases.
`nft_tier_unlocked`	A tier NFT unlock becomes available to you.
`system_announcement`	A protocol-wide announcement.
`airdrop_claimed`	An airdrop is claimed for your wallet.
`referral_rewarded`	A referral reward is credited.
`kyc_tier_upgraded`	Your KYC tier is upgraded.
`ruffler_ticket_won`	You win a Ruffler ticket.
`ruffler_round_drawn`	A Ruffler round is drawn.

Helius NFT webhooks (inbound)

MAGMA's tier NFTs (MLAVA / MGNSS / MSPEC) map a wallet to a Conviction tier. To keep that mapping current when an NFT changes hands, MAGMA receives inbound webhooks from Helius on transfer events and re-derives the owner's tier. These endpoints are called by Helius, server-to-server — a client never calls them — but integrators that index or resell tier NFTs should understand the flow.

Endpoint	Method	Purpose
`/v1/nft/webhook/helius`	POST AUTH	Helius webhook for transfer events.
`/v1/nft/webhook/transfer`	POST AUTH	MLAVA / MGNSS transfer webhook.

Shared secret required

Both webhook endpoints require an x-webhook-secret header that must match the configured secret. Requests without a valid secret are rejected. This secret is server-side only and is not an end-user wallet signature or an admin credential. See Authentication.

POST /v1/nft/webhook/helius
x-webhook-secret: <configured-webhook-secret>
Content-Type: application/json

To read the resulting tier state for a wallet or a mint, use the public NFT reads (GET /v1/nft/wallet/:wallet, GET /v1/nft/score/:mintAddress) documented in NFT.

Web Push subscription​

1. Get the VAPID public key​

2. Create the subscription in the client​

3. Register the subscription with MAGMA​

Per-type preferences​

Notification types​

Helius NFT webhooks (inbound)​

See also​