Source Zendesk Support: add ticket_events stream from incremental/ticket_events.json

[Henrique Pereira (hpereira98)]

Source Zendesk Support: add ticket_events stream from incremental/ticket_events.json

What problem are you trying to solve?

The source-zendesk-support connector does not expose the Incremental Ticket Events Export endpoint (GET /api/v2/incremental/ticket_events.json). This leaves a gap in the data model: there is no way to obtain the complete event-level timeline of every Zendesk ticket through the official connector.

Data the existing streams do not provide

The connector already exposes adjacent streams, but none of them substitute for ticket_events:

Stream	What it gives	What it doesn't
ticket_audits	Audit records aggregated per ticket update	One audit per update, not per individual event; missing via_reference_id, system metadata, and event-typing granularity. Critically, the list endpoint excludes archived tickets (Zendesk auto-archives ~120 days after Closed), so historical data is effectively unavailable through this stream
ticket_metric_events	SLA / metric-related events only (e.g. apply_sla, fulfill, reply_time, update_status)	No Comment, Notification, NotificationGenerated, Create, Cc, External, etc.
ticket_comments	Comments only	No status changes, assignments, automations, triggers, notifications, system events
tickets	Snapshot per ticket	Loses history; can't reconstruct ordering or causality between changes

The ticket_events endpoint is the only one that returns the complete chronological stream of every event Zendesk generated (Audit, Comment, Notification, NotificationGenerated, Create, Cc, External, and more), each tagged with the triggering source (via, via_reference_id, system) and the contributing updaters.

Zendesk explicitly recommends this endpoint for change-data capture

The Zendesk Ticket Audits API documentation directs users away from the list audits endpoint for this use case:

"This endpoint should not be used for capturing change data. When continually chasing the tail of a cursor, some records will be skipped."

…and points to the Incremental Ticket Event Export as the recommended alternative. The official Airbyte connector should expose what the Zendesk team themselves recommend as the canonical source for ticket change history.

Use cases blocked today

Without this stream, the following analytics are either impossible or require ugly approximations from other streams:

1. Ticket lifecycle reconstruction — accurate time-in-status, time-to-first-response per ticket, escalation paths, reopens. Currently approximated from ticket_audits but loses the per-event granularity.
2. Automation / trigger attribution — via_reference_id on a ticket event lets you trace which trigger or automation produced a given change. Not available anywhere else.
3. Notification analytics — Notification and NotificationGenerated events let teams measure outbound communication volume, deliverability proxies, and per-rule notification frequency. Today these events are invisible.
4. Audit-grade event log for compliance — many support orgs need a row-per-event, append-only ledger of everything that happened on a ticket. ticket_audits aggregates events per update, losing this granularity.
5. System / channel metadata — system (client, IP, location) and via (channel, source) on each event power channel-attribution and abuse-detection analytics.

Community impact

Our team has worked around this gap by building custom declarative manifest connectors that duplicate most of source-zendesk-support just to add this one stream. Bringing it into the official connector removes that duplication and gives community-built pipelines:

• the connector's built-in HTTPAPIBudget for /api/v2/incremental/.* (already correctly rate-limited at 10/min)
• the shared error handler with proper 403/permissions surfacing
• the concurrent CDK + auth refresh paths that the manifest-only declarative source doesn't get
• a consistent schema reviewed and maintained alongside the other ticket-* streams

Proposed solution

Add a new declarative stream ticket_events to airbyte-integrations/connectors/source-zendesk-support/manifest.yaml. It can closely mirror the existing ticket_metric_events_stream:

• Endpoint: incremental/ticket_events.json
• Cursor field: timestamp (Unix epoch seconds, same cursor_incremental_sync format already used by other incremental_export streams)
• Cursor filter: start_time
• Primary key: id
• Pagination: end_of_stream_paginator (cursor-based via next_page URL, stop on end_of_stream)
• Sync mode: Incremental
• Record extractor: DpathExtractor on ticket_events

Schema fields (per Zendesk docs): id, ticket_id, timestamp, created_at, updater_id, event_type, via, via_reference_id, system, updaters[], child_events[].

Important note on cursor semantics

Like the tickets stream (see the connector's CONTRIBUTING.md), this endpoint filters internally on generated_timestamp, not on the record's timestamp field. When a ticket is archived or deleted, all its events are re-stamped with the generated_timestamp of that operation, so a start_time query can return events with timestamp values from years earlier. This is documented Zendesk behavior. The new stream documentation should call this out so users don't mistake it for a connector bug. De-duplication on the destination side via primary key id handles the resulting overlap cleanly.

[airbyte-support-bot]

Hi Henrique Pereira (@hpereira98), thank you for the detailed feature request!

The proposed ticket_events stream is well scoped, and the notes about Zendesk's Incremental Ticket Event Export semantics are helpful context for implementation and documentation. We've escalated this to our team for investigation and prioritization: https://github.com/airbytehq/oncall/issues/12617

---

Need more help? Join Airbyte Community Slack for peer support, or if you're a Cloud customer, open a support ticket referencing this URL.

[Henrique Pereira (hpereira98)]

Adding context: we've already forked the official connector's manifest and added ticket_events to it via a custom declarative source on our side. It's been running in production and working as expected - same incremental/ticket_events.json endpoint, mirroring the ticket_metric_events stream pattern with cursor_field: timestamp, cursor_filter: start_time, end_of_stream_paginator. Happy to upstream the change as a PR whenever the team is ready.