Document webhook payloads and event keys

[qayshp]

Summary

• document the webhook HTTP method, content type, and stable { type, data } envelope
• add representative payloads for message, typing-indicator, and primitive-value events
• replace the stale prose event list with every subscription key currently exposed by the server
• document wildcard subscriptions and best-effort, non-retried delivery
• link the server constant that is the source of truth for event keys

Why

The existing page explains that BlueBubbles can send webhooks but does not show the request body a receiver must decode. It also lists only a subset of the events exposed by the server.

Fixes BlueBubblesApp/bluebubbles-server#797.

Compatibility

The examples intentionally describe representative fields instead of promising one exhaustive data schema. Event data varies by event, server and macOS version, message type, and notification-size limits.

Validation

• git diff --check origin/master...HEAD passes
• all 26 documented subscription keys match webhookEventOptions on current server master and development, in the same order
• all four JSON examples parse successfully
• the method, content type, envelope, wildcard behavior, and delivery wording match WebhookService and the inspected emitters
• a route-aware live test on the authorized SIP-custom host captured valid display: true and display: false typing events through the helper → server → HTTP webhook path

The live test sent no message or attachment, printed no personal identifier, and removed its temporary webhook and artifacts afterward.

[qayshp]

Self-review completed. I found one maintainability concern to address before this draft is ready.

[qayshp]

Validation update

• git diff --check origin/master...HEAD passes.
• All 26 documented subscription keys match the server's current webhookEventOptions, in the same order.
• All four JSON examples parse successfully.
• The POST method, JSON content type, { type, data } envelope, wildcard behavior, and best-effort delivery wording match WebhookService and the inspected emitters.

This was a source-and-format validation pass. No live message or typing action was performed, and no payload values or user data were captured.

A live typing-indicator capture remains deferred to the SIP-disabled Private API host. If run, it will use only the user-designated two-recipient conversation and will require an explicitly announced real typing action.

[qayshp]

Remote validation follow-up (SIP-custom Sequoia Intel host)

The remote host was ready for a live Private API check: the server reported Private API enabled, the helper connected, and an iMessage account available.

A positive typing-indicator webhook test could not be performed under the required two-recipient-conversation constraint. That conversation is necessarily a group chat, and the current server implementation intentionally returns before emitting a typing event when the chat GUID is a group GUID. As a result, typing in that conversation cannot validate the documented positive payload.

The static source-chain validation still passes: the event key exists, start/stop typing maps to display: true/false, the emitted data is { display, guid }, and the webhook service wraps it as { type, data } JSON.

No typing action or message was sent for this test. A true end-to-end positive test will require explicit authorization to use a 1:1 conversation and a temporary loopback webhook receiver.

[qayshp]

Authorized 1:1 partial end-to-end validation

Ran an additional test on the SIP-custom Sequoia host using an existing authorized 1:1 iMessage conversation. No draft text was entered and no message was sent. Instead, the server requested the current typing state from the connected Private API helper and dispatched the result to a temporary loopback-only webhook receiver.

Passed:

• Exactly one webhook event was received.
• Content-Type was JSON.
• The root keys were exactly type and data.
• type was typing-indicator.
• The data keys were exactly display and guid.
• display was the expected boolean false.
• The GUID matched the requested 1:1 conversation in memory; no identifier was printed.
• The temporary webhook was deleted after the check.

This validates the Private API helper → server event handler → HTTP webhook envelope for the stopped/not-typing state. It does not validate a genuine display: true event. The authorized iMessage destination is an alias of the server account rather than an independent remote participant, and the other authorized destination is SMS-only, which cannot emit iMessage typing indicators. A positive live check still requires a separate iMessage identity typing into a 1:1 conversation.

[qayshp]

Final route-aware live typing validation

Retested with an authorized independent iMessage participant in the 1:1 conversation visibly open on the SIP-custom Sequoia server Mac. The participant typed and held an unsent draft character, and the typing indicator was visibly present in that same server-Mac conversation.

The initial harness had selected the unique phone-number-based chat GUID for that contact. A route-aware rerun showed that Messages actually emitted the typing events through a different, email-based iMessage handle associated with the displayed conversation. Sanitized helper metadata showed exactly one typing GUID during the test window; it was an iMessage 1:1, not a group. No address or GUID was printed.

The route-aware loopback receiver captured both states on that single route:

• display: true while the participant was typing.
• display: false after the draft was cleared/stopped.
• JSON Content-Type.
• Root keys exactly type and data.
• type === "typing-indicator".
• data keys exactly display and guid.
• Boolean display values.

Result: the live helper → server → HTTP webhook path passes for both positive and negative typing states. The earlier helper-failure diagnosis is retracted; the failure was in the test harness filtering only the contact’s phone-based GUID while Messages used its email-based route.

The test harness sent no message or attachment. The temporary webhook and all temporary artifacts were removed, and the installed server remained healthy.

[qayshp]

Merge-readiness audit: the 26 documented event keys still match current server master and development exactly and in order. JSON, relative-link, fenced-code, shell-syntax, and diff checks pass. The final route-aware live typing result above remains the authoritative end-to-end result and supersedes the earlier partial attempts.