Choose activity events
Use the event catalog to read the fields for each event. For example, a message event can trigger an inbox refresh. Before sending an automatic reply, check that you have not handled the event already. Also check that your app still has access to the account.
Configure delivery
Choose how your app receives events:Read the envelope
Each webhook event has outer fields, called its envelope. These fields includeeventId, type, schemaVersion, order, occurredAt, environment, integrationId, externalOauthClientId, authorizationId, linkedAccountId, test, and data.
Use authorizationId to identify the authorization and linkedAccountId to select the affected account. data contains the fields documented for that event type. The fields depend on the event type. Check that event’s fields in the API reference before reading message, user, or media details.
Verify and acknowledge deliveries
Follow Verify and handle webhooks to check the original body and timestamp. UseeventId to detect duplicates. Return a success response after you accept an event. Use order to avoid applying old linked-account updates over newer ones.
A delayed activity event does not prove the account is still connected. Read linked accounts before acting when current status or permissions matter.
Receive Realtime over Server-Sent Events
Requesthttps://api.ofauth.com/v3/realtime/events?linkedAccountId= with the linked account ID, Accept: text/event-stream, and the access token in Authorization: Bearer:
retry: 3000 and an id: line with no event (its starting cursor; keep it as your last event ID). Each event has id (the event’s order), event (its type), and data (the event JSON, shown below). A : heartbeat comment arrives every 15 seconds.
To resume after a disconnect, send the last id as Last-Event-ID (or the lastEventId query parameter). OFAuth replays missed events from the last 15 minutes, up to 1,000 events. If it can’t, it sends one event: resync: fetch the current data from the API, then keep listening. Delivery is at least once, so skip an eventId you have handled.
Before the stream ends on purpose, it sends event: closed with data: {"reason": …}:
unavailable: reconnect withLast-Event-IDafter a short delay. Do the same when the stream ends withoutclosed.reauth: the access token expired or was revoked, or the account is no longer shared with your app. Refresh the access token and reconnect once. Stop if that is refused (401or403).replaced: more than 10 streams were open for this linked account and authorization, and this was the oldest browser stream. Don’t reconnect it.
replaced. Server streams are never replaced: when all 10 are server streams, a new stream gets 429 stream_limit; close one first.
Errors before the stream starts: 400 for a malformed request, 401 for missing or denied authentication, 406 for an Accept header that excludes both text/event-stream and */*, 429 stream_limit (10 server streams already open), and 503 realtime_unavailable (retry later).
The stream envelope
Stream events carryeventId, type, schemaVersion, order, receivedAt, environment, integrationId, linkedAccountId, test, and data. The stream envelope differs from the webhook envelope. Lifecycle events are webhook-only. When the account receives an inbox-count update, the stream can send:
Test and troubleshoot
For webhooks, verify the destination, then trigger a matching action in Sandbox or Test. To receive the delivery locally, use a Cloudflare Quick Tunnel. For the stream, connect with a Test account and trigger an inbox-count change on that account. Confirm that the logged account and environment match your application records. An open stream alone does not prove that a matching activity event has occurred. Keep sample test data out of production records. Events about account and access changes usetest: true in Test, even for real accounts. Use environment to select the correct app records.
For missing events, verify the destination environment, Realtime setting, selected authorization, and account status. For invalid signatures, use the destination’s current secret and the unmodified raw body. For duplicates, check that your app detects repeated eventId values. If your data is out of date, compare order values for the same account and fetch the current data.
Follow Messaging to build inbox workflows and Webhooks for account and access events and delivery checks.