Relay Hooks

Published Jan 30, 2026

kind 30027

Relay Hooks

draft optional

This NIP defines a way for users to register new event hooks with relays and forward them to an HTTP API.

Each kind 30027 event registers a hook with the following structure:

{
  "kind": 30027,
  "tags": [
    ["d", "<subscription_id>"],
    ["relay", "<normalized relay url>"], 

    ["filter", "<stringified nostr filter>"],
    ["ignore", "<stringified nostr filter>"] // optional

    ["callback", "<callback URL to forward events to>"], 
  ]
  // other fields
}

When a relay receives a new event, it MUST match it against all current registrations and POST the JSON-stringified event to the callback URL with Content-Type: application/json.

Tags relay and callback are required.

All tags MAY appear multiple times to represent a logical OR.

Supporting relays MUST only activate the registration if the "relay" tag matches their own URL.

Supporting relays MUST reply with custom OK messages:

["OK", "b1a649ebe8...", true, "subscribed"] when the relay will fulfill the subscription
["OK", "b1a649ebe8...", false, "<error_message>"] when the relay will not fulfill the subscription

Clients should check the "subscribed" return to see if the relay supports the type of hook the client is creating.

If the callback URL responds with a 404 status code, the relay SHOULD delete the subscription. Relays MAY delete subscriptions at their discretion (e.g., due to expiration, inactivity, callback 500 errors, etc).

Example

In this case, a hook for replies and reactions citing a user OR a hashtag the user is following, ignoring anything that tags footstr, are forwarded to Amethyst's Push server.

{
  kind: 30027,
  tags: [
    ["d", "amethyst-push-notifications"],
    ["relay", "wss://nos.lol/"],
    ["filter", "{\"kinds\": [1, 7], \"#p\": [\"<user pubkey>\"]}"],
    ["filter", "{\"kinds\": [1, 7], \"#t\": [\"<following hashtag>\"]}"],
    ["ignore", "{\"#t\": [\"footstr\"]}"],
    ["callback", "https://push.amethyst.social/"]
  ],
}