Overview
The published Revenue contract does not define a general webhook subscription surface. Preserve this public route by implementing provider-supported polling: direct paginated audit reads for administrative changes or asynchronous activity exports for emails, meetings, and files.
Prerequisites
- Chosen feed type, organization scope, and authorized fields
- Monotonic time window or pagination checkpoint with overlap policy
- Deduplication store and downstream event schema
Instructions
Step 1: Choose the supported source
Use GET /audit/events for paginated audit changes or POST /export/activity plus the export-job lifecycle for activity data.
Step 2: Freeze the window
Record inclusive and exclusive boundaries, page limit, overlap allowance, timezone, and the first checkpoint before requesting data.
Step 3: Read or queue
Page audit events in stable order, or queue one activity export and persist its job ID before polling.
Step 4: Normalize event identity
Derive a deterministic key from provider identifiers, event type, actor, timestamp, and source window; retain the source job or page lineage.
Step 5: Deduplicate and advance
Publish only validated unseen events, then advance the checkpoint atomically after the downstream sink acknowledges the batch.
Step 6: Detect gaps and replay
Monitor lag, empty windows, page discontinuity, aborted jobs, and reconciliation counts; replay from the last safe checkpoint within retention.
Authentication
Use the Revenue apikey header and an identity authorized for the selected audit or activity data. Do not log actor identities, email content, meeting details, filenames, or the token in event-processing telemetry.
Tool Discipline
Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.
Output
- Feed definition and checkpoint policy
- Normalized event batches with provider lineage and deterministic keys
- Lag, gap, deduplication, replay, and checkpoint receipts
Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.
Examples
An audit feed polls with a small overlap, deduplicates by provider event identity, publishes a validated batch, and advances its cursor only after the sink acknowledges it. No unsupported webhook registration is attempted.
Error Handling
| Failure | Response |
|---|---|
| Page or window gap is detected | Stop checkpoint advancement and replay from the last verified boundary. |
| Activity export aborts | Retain the job ID and request fingerprint, diagnose the failure, and avoid blind duplicate submission. |
| Downstream acknowledgement is unknown | Replay the same deterministic batch and let deduplication prevent duplicate effects. |