# H1DR4 Partner Event Protocol

> Canonical HTML: https://h1dr4.dev/articles/h1dr4-partner-event-protocol
> Machine index: https://h1dr4.dev/llms.txt

The H1DR4 Partner Event Protocol is the authenticated integration surface for organizations that need filtered live case activity, durable replay, and controlled write-back.

## Transport contract

- Default delivery: poll `GET https://h1dr4.dev/api/v1/partners/events?subscription={name}&after={cursor}` every five seconds.
- Optional live endpoint: `wss://h1dr4-api-305876265828.europe-west1.run.app/v1/partners/stream` when enabled.
- Authentication: `Authorization: Bearer h1p_...`
- Delivery: at least once, ordered by a monotonic cursor.
- Write safety: partner-scoped idempotency keys make case and tip retries duplicate-safe.
- Control plane: Google Cloud Datastore stores credentials, subscriptions, event cursors, acknowledgements, and write claims; no additional Supabase schema is required.

## Event surfaces

Partners can subscribe to case creation and updates, new tips, tip votes, and on-chain incident or evidence activity. Filters support event glob patterns, surfaces, case IDs, chains, classifications, incident types, tip kinds, minimum loss, tags, and self-origin exclusion.

## Write-back

Partners use the same bearer key with `POST https://h1dr4.dev/mcp`. Canonical tools include `h1dr4_get_case`, `h1dr4_create_case`, `h1dr4_submit_tip`, `h1dr4_vote_tip`, and the on-chain registry tools. Every partner write carries a stable idempotency key and source URL where the tool requires one.

Read the complete protocol, message envelopes, reconnect sequence, filter schema, scopes, examples, and error behavior in [section 28 of the developer manual](https://h1dr4.dev/docs.md#28-partner-event-protocol).