DeHub Webhooks and Notifications API

Your server and DeHub talk both ways. DeHub posts signed events to your webhook, and your server sends notifications to people who added your app.

Receiving events

Set webhookUrl in your manifest. DeHub sends a POST with this body:

{ "event": "app_added", "token": "eyJhbGciOiJFUzI1NiIs…" }

Event	When
`app_added`	Someone added your app. They can now receive your notifications.
`app_removed`	Someone removed your app. Stop notifying them.
`payment`	Someone paid your app with `dehub.actions.pay()`. The token adds `amount`, `chainId`, `txHash` and `memo`.
`tip`	Opt-in. The owner wallet was tipped. Adds `actor`, `amount`, `currency` and `postId` when the tip was on a post.
`follow`	Opt-in. Someone followed the owner wallet. Adds `actor`.
`mention`	Opt-in. Someone mentioned the owner wallet. Adds `actor` and `postId`.
`ping`	A test sent from the Webhook button on dehub.io/apps/dev.

tip, follow and mention are about the wallet that owns your app, so sub is that wallet. List the ones you want in your manifest, then submit it again:

"webhookUrl": "https://tipjar.example.com/api/dehub-webhook",
"webhookEvents": ["tip", "follow", "mention"]

token is a signed JWT with typ: "event", the event name, sub (the user's wallet) and aud (your domain). Verify it with the same public keys as sign-in tokens, and ignore any body whose token does not verify. Answer within 5 seconds with a 2xx. A network error or 5xx is retried once after 3 seconds. Every attempt is listed under Webhook on dehub.io/apps/dev. Still treat dehub.context's client.added as the source of truth when someone opens your app.

Sending notifications

Create a notification key on dehub.io/apps/dev. It is shown once; DeHub keeps only a hash, so a lost key is replaced, not recovered.

curl -X POST https://aigxuutjaqsywioxjefr.supabase.co/functions/v1/miniapp-notify \
  -H 'Authorization: Bearer dhmk_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "notificationId": "turn-42",
    "title": "Your turn",
    "body": "Sam played a move. Tap to answer.",
    "targetUrl": "https://chess.example.com/game/42",
    "wallets": ["0xabc…"]
  }'

Field	Rules
`notificationId`	Required. Up to 128 characters. The same id reaches a person at most once in 24 hours.
`title`	Required. Up to 32 characters.
`body`	Up to 128 characters.
`targetUrl`	An https link on your app's domain, opened when the notification is tapped.
`wallets`	Who to notify. Leave it out to notify everyone who added your app (up to 1,000 a call).

The answer says who was sent to and why anyone was skipped: { sent, sentTo, skipped: { duplicate, rateLimited, notAdded } }. Each person gets at most one notification every 30 seconds and ten a day from your app, and only if they added it and left its notifications on.

Payment receipts

dehub.actions.pay() resolves only after DeHub has checked the transfer on chain, and hands your app a signed receipt to verify on your server. The payment webhook is a second copy for your server, sent in the background. See Payments.