Hooks

Overview Client mods Auto-updates API endpoints Hooks Webhooks Actions

Hook events are pushed to client mods over the plugin channel and to backend apps over webhooks. Every event is gated by a backing read scope, and grouped here by who can see it.

Event envelope

Every hook event shares this envelope, whether it arrives on a client mod over the plugin channel or on a backend webhook. Only data changes per event type.

{
  "id": "evt_01J...",
  "type": "player.enchant_proc",
  "version": 1,
  "createdAt": "2026-06-04T00:00:00.000Z",
  "serverScope": "aether",
  "producer": { "kind": "minecraft_server", "id": "aether" },
  "actor": { "playerId": "00000000-0000-0000-0000-000000000000" },
  "subject": { "playerId": "00000000-0000-0000-0000-000000000000" },
  "visibility": "self",
  "requiredScopes": ["hooks.player.enchant_proc:read"],
  "data": { /* event-specific fields */ }
}

idstring

Globally unique, stable id. Delivery is at least once, so dedupe on this.

typestring

The event type from the catalog below, e.g. player.enchant_proc.

versionnumber

Payload contract version. Branch on it when a payload shape changes.

createdAtISO 8601

When the event occurred.

serverScopestring

Which server it happened on, e.g. aether or celestial.

producerobject

What emitted the event, as { kind, id }.

actorobject

Who caused it, with a playerId when a player is known.

subjectobject

Who or what the event is about — a player, gang, or the server.

visibilitystring

self, gang, server, or app owner — who is allowed to receive it.

requiredScopesstring[]

The scopes that gate this event.

dataobject

Event-specific payload. Some events pass runtime data through unchanged — read it defensively.

Your player

Events about your own player, delivered only to the player who granted access.

Enchant proc

player.enchant_proc

Fires when one of your enchants procs.

hooks.player.enchant_proc:read

Client

Webhook

Cooldowns changed

player.cooldowns.changed

Fires when your cooldowns change.

player.cooldowns:read

Client

Webhook

Effects changed

player.effects.changed

Fires when your active effects change.

player.effects:read

Client

Webhook

Absorber used

player.absorber.used

Fires when your absorber is used.

hooks.player.absorber:read

Client

Webhook

Command succeeded

player.command.succeeded

Fires when one of your approved commands runs.

hooks.player.command:read

Client

Webhook

Pet changed

player.pet.changed

Fires when your active pet changes.

player.pets:read

Client

Webhook

Trinket changed

player.trinket.changed

Fires when your trinkets change.

player.trinkets:read

Client

Webhook

Chat channel changed

player.chat_channel.changed

Fires when your active chat channel changes.

player.chat_channel:read

Client

Webhook

Bandit killed

bandit.killed

Fires when you kill a bandit.

hooks.bandit.kill:read

Client

Webhook

Library changed

player.library.changed

Fires when your library, or a library shared with you, gains or loses items.

player.library:read

Client

Webhook

Relationship bypass for webhooks

Library access changed

player.library.access.changed

Fires when a library share you own or receive is added, changed or removed.

player.library:read

Client

Webhook

Relationship bypass for webhooks

Vault contribution changed

player.vault.contribution.changed

Fires about once a second while your damage or rank in a mine vault raid changes, while you are in the top 25.

events:read

Client

Webhook

Emblem changed

player.emblem.changed

Fires when your equipped emblem, its tier or your buffs toggle changes.

player.emblems:read

Client

Webhook

Emblem progress changed

player.emblem.progress.changed

Fires at most every five seconds while your emblem progress changes.

player.emblems:read

Client

Webhook

Emblem unlocked

player.emblem.unlocked

Fires when you unlock an emblem tier.

player.emblems:read

Client

Webhook

Top credits changed

player.top_credits.changed

Fires when your Top Credit balance changes.

player.top_credits:read

Client

Webhook

Satchel backpack changed

player.satchel_backpack.changed

Fires when one of your satchel backpacks changes contents or energy.

player.satchels:read

Client

Webhook

Custom set changed

player.custom_set.changed

Fires when you complete or break a Death or Greed set.

player.custom_sets:read

Client

Webhook

Payday changed

player.payday.changed

Fires when your Greed set payday starts or ends.

player.custom_sets:read

Client

Webhook

Death mark changed

player.death_mark.changed

Fires when a death mark is placed on you, cleared or expires.

player.custom_sets:read

Client

Webhook

Ground Zero points changed

player.ground_zero.points.changed

Fires about once a second while your Ground Zero points change.

player.ground_zero:read

Client

Webhook

Your gang

Events shared with the members of your current gang.

Gang chat message

gang.chat.message.created

Fires when a message is posted in your gang chat.

gang.messages:read

Client

Webhook

Relationship bypass for webhooks

Gang ping

gang.ping.created

Fires when a gang or truce ping is created.

gang.pings:read

Client

Webhook

Relationship bypass for webhooks

Server-wide

Live world events broadcast for the whole server.

Server event changed

server.event.changed

Fires when the current public server event changes.

events:read

Client

Webhook

Event schedule changed

server.event.schedule.changed

Fires when the server event schedule changes.

events:read

Client

Webhook

Meteor landing changed

server.meteor.landing.changed

Fires when meteor landing information changes.

server.meteors:read

Client

Webhook

Merchant spawned

server.merchant.spawned

Fires when a merchant spawns.

server.merchants:read

Client

Webhook

Merchant despawned

server.merchant.despawned

Fires when a merchant despawns.

server.merchants:read

Client

Webhook

Guards snapshot changed

server.guards.snapshot.changed

Fires when controlled guard status near you changes.

server.guards:read

Client

Webhook

Relationship bypass for webhooks

Weather changed

server.weather.changed

Fires when a weather event starts or ends.

events:read

Client

Webhook

Weather surge changed

server.weather.surge.changed

Fires when a weather surge starts or ends.

events:read

Client

Webhook

Mine vault raid started

server.vault.raid.started

Fires when a mine vault raid begins.

events:read

Client

Webhook

Mine vault raid ended

server.vault.raid.ended

Fires when a mine vault raid ends, with the outcome and top damagers.

events:read

Client

Webhook

Prison Break phase changed

server.prisonbreak.phase.changed

Fires when the Prison Break match moves to a new phase.

events:read

Client

Webhook

Top credit checkpoint paid

server.top_credit.checkpoint.completed

Fires when a Top Credit checkpoint pays out, with the awarded ranks.

player.top_credits:read

Client

Webhook

Ground Zero reset changed

server.ground_zero.reset.changed

Fires when a Ground Zero reset is scheduled, starts, completes or retries.

player.ground_zero:read

Client

Webhook

App owner

Operational events about your app's sessions, delivered to webhooks.

Session connected

mod.session.connected

Fires when a player connects with your mod.

mod.sessions:read

Webhook

Session disconnected

mod.session.disconnected

Fires when a player disconnects from your mod.

mod.sessions:read

Webhook