docs: add Zendesk webhook integration guide#253
Conversation
Add documentation for sending Zendesk ticket events as goal events to the ABsmartly Collector API using Zendesk Webhooks and Triggers.
joalves
requested review from
bmsilva,
calthejuggler,
marcio-absmartly and
mario-silva
as code owners
WalkthroughAdds a new MDX document under docs/Third-party-integrations describing how to publish Zendesk ticket events as ABsmartly goal events via a Zendesk webhook. The guide lists prerequisites, step‑by‑step instructions to create the webhook and trigger (including headers, endpoint and a sample JSON payload), how to create the corresponding ABsmartly goal, a /context payload reference, available Zendesk placeholders, event tracking variations, verification steps and support contact details. Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Comment |
✅ Deploy Preview for absmartly-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/Third-party-integrations/Zendesk-Integration.mdx`:
- Around line 30-31: Update the prose under the "Endpoint URL" section so it
explicitly instructs users to append "/v1/context" (not just "/context") and
reference the HTTP method "PUT /v1/context"; replace the ambiguous phrase that
currently says to append "/context" with a clear statement like "append
/v1/context (use PUT /v1/context)" and ensure the example URL
`https://your-subdomain.absmartly.io/v1/context` remains as the canonical
example.
- Around line 67-89: The example payload uses
{{ticket.created_at_with_timestamp}} which renders as an ISO 8601 string and is
unquoted in the JSON and mismatches the schema; update the example so
publishedAt is a numeric Unix-millisecond timestamp (int64) instead of the ISO
string: replace or annotate the publishedAt and goals[].achievedAt fields (and
their uses of {{ticket.created_at_with_timestamp}}) to show a Zendesk-supported
milliseconds value or add a short note that you must convert the ISO timestamp
to Unix ms via an intermediary or custom field before sending to the ABsmartly
Collector API so the JSON remains valid and matches the publishedAt/achievedAt
int64 schema.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: b021d0b1-4396-493d-baba-9f9e2d1aa2f7
📒 Files selected for processing (1)
docs/Third-party-integrations/Zendesk-Integration.mdx
| - **Endpoint URL**: Your ABsmartly Collector endpoint followed by `/context`. | ||
| For example: `https://your-subdomain.absmartly.io/v1/context` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n docs/Third-party-integrations/Zendesk-Integration.mdx | head -40Repository: absmartly/docs
Length of output: 2089
🌐 Web query:
ABsmartly Collector API context publish endpoint documentation
💡 Result:
ABsmartly Collector API — Context “publish” endpoint
- HTTP method / path:
PUT /v1/context(example base URL shown in docs:https://sandbox.absmartly.io) [1] - Purpose: publish exposures, goals, and attributes collected in a context to the ABsmartly collector [1]
Authentication
- Header:
X-API-Key: <your key>(apiKey auth) [2]
Required request headers
X-Agent(SDK user-agent string, e.g.absmartly-Java-SDK v1.0.1) [1]X-Environment(e.g.development) [1]X-Application(e.g.www) [1]X-Application-Version(int64) [1]
JSON request body (high level)
publishedAt(int64 timestamp; required) [1]units(array; required) — objects withtypeanduid[1]- Optional flags:
hashed(bool),historic(bool) [1] - Optional arrays:
exposures(experiment exposure events) [1]goals(tracked goal events) [1]attributes(context attributes for segmentation) [1]
Response (success)
- JSON like:
okplus optionalwarnings[]/errors[]entries (each includesbatchIndex,eventIndex,subject,message) [1]
Sources: Publish Experiment Events (context publish) [1]; Collector API overview/auth scheme [2].
[1] (docs.absmartly.com)
[2] (docs.absmartly.com)
Citations:
- 1: https://docs.absmartly.com/docs/SDK-API/context-publish
- 2: https://docs.absmartly.com/docs/sdk-api/absmartly-collector-api/
Specify /v1/context in the endpoint instructions.
Line 30 instructs to append /context, but the ABsmartly Collector API endpoint is documented as PUT /v1/context. The example on line 31 is correct; updating the prose to explicitly reference /v1/context will prevent readers from omitting the version prefix.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/Third-party-integrations/Zendesk-Integration.mdx` around lines 30 - 31,
Update the prose under the "Endpoint URL" section so it explicitly instructs
users to append "/v1/context" (not just "/context") and reference the HTTP
method "PUT /v1/context"; replace the ambiguous phrase that currently says to
append "/context" with a clear statement like "append /v1/context (use PUT
/v1/context)" and ensure the example URL
`https://your-subdomain.absmartly.io/v1/context` remains as the canonical
example.
| ```json | ||
| { | ||
| "publishedAt": {{ticket.created_at_with_timestamp}}, | ||
| "units": [ | ||
| { | ||
| "type": "email", | ||
| "uid": "{{ticket.requester.email}}" | ||
| } | ||
| ], | ||
| "goals": [ | ||
| { | ||
| "name": "zendesk_ticket_created", | ||
| "achievedAt": {{ticket.created_at_with_timestamp}}, | ||
| "properties": { | ||
| "ticket_id": "{{ticket.id}}", | ||
| "subject": "{{ticket.title}}", | ||
| "priority": "{{ticket.priority}}", | ||
| "channel": "{{ticket.via}}" | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -type f -name "*Zendesk*" | head -20Repository: absmartly/docs
Length of output: 113
🏁 Script executed:
git ls-files | grep -i zendesk | head -20Repository: absmartly/docs
Length of output: 111
🏁 Script executed:
git ls-files docs/Third-party-integrations/ | head -30Repository: absmartly/docs
Length of output: 805
🏁 Script executed:
cat -n docs/Third-party-integrations/Zendesk-Integration.mdx | sed -n '50,100p'Repository: absmartly/docs
Length of output: 2030
🌐 Web query:
Zendesk ticket.created_at_with_timestamp placeholder format
💡 Result:
{{ticket.created_at_with_timestamp}} outputs the ticket’s creation time as an ISO 8601 UTC timestamp, e.g. 2024-11-06T07:04:20Z (format: YYYY-MM-DDTHH:MM:SSZ). [1][2]
🌐 Web query:
ABsmartly Collector API publishedAt achievedAt field type int64 schema
💡 Result:
In the ABsmartly Collector API Publish Experiment Events endpoint (PUT /v1/context), the request-body schema defines:
publishedAt: int64, required (time at which the publish request was made). [1]goals[].achievedAt: int64, required (time the goal was achieved). [1]
Although the docs don’t explicitly state the unit, the example values (e.g., 1609244179528) indicate these are Unix timestamps in milliseconds. [1]
Source:
[1] (docs.absmartly.com)
Citations:
🏁 Script executed:
cat -n docs/Third-party-integrations/Zendesk-Integration.mdx | sed -n '1,66p'Repository: absmartly/docs
Length of output: 3423
🏁 Script executed:
cat -n docs/Third-party-integrations/Zendesk-Integration.mdx | sed -n '90,150p'Repository: absmartly/docs
Length of output: 3171
The sample payload is incompatible with the documented schema.
The Payload Reference (line 113) correctly specifies that publishedAt should be a Unix millisecond timestamp, but the JSON example at lines 67–89 uses {{ticket.created_at_with_timestamp}}, which Zendesk renders as an ISO 8601 string (e.g., 2024-11-06T07:04:20Z). This causes two failures: (1) the unquoted string makes the JSON invalid, and (2) the string type does not match the required int64 schema for the ABsmartly Collector API. The example must show either a Zendesk-supported Unix-millisecond conversion, a custom field that provides milliseconds, or explicit guidance that an intermediary service is required to transform the timestamp before sending to ABsmartly.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/Third-party-integrations/Zendesk-Integration.mdx` around lines 67 - 89,
The example payload uses {{ticket.created_at_with_timestamp}} which renders as
an ISO 8601 string and is unquoted in the JSON and mismatches the schema; update
the example so publishedAt is a numeric Unix-millisecond timestamp (int64)
instead of the ISO string: replace or annotate the publishedAt and
goals[].achievedAt fields (and their uses of
{{ticket.created_at_with_timestamp}}) to show a Zendesk-supported milliseconds
value or add a short note that you must convert the ISO timestamp to Unix ms via
an intermediary or custom field before sending to the ABsmartly Collector API so
the JSON remains valid and matches the publishedAt/achievedAt int64 schema.
Co-authored-by: Cal Courtney <cal@absmartly.com>
There was a problem hiding this comment.
♻️ Duplicate comments (2)
docs/Third-party-integrations/Zendesk-Integration.mdx (2)
30-31:⚠️ Potential issue | 🟠 MajorUse
/v1/contextconsistently throughout the guide.Line 30 tells readers to append
/context, and Line 109 repeatsPUT /context, but Line 31 already shows/v1/context. Following the prose as written can point readers at a different path from the example, so the instructions and reference section should all use the same versioned endpoint.What is the documented ABsmartly Collector API path for publishing context events: `PUT /context` or `PUT /v1/context`?Also applies to: 108-109
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/Third-party-integrations/Zendesk-Integration.mdx` around lines 30 - 31, The guide inconsistently references the collector endpoint as both "/context" and "/v1/context"; update every occurrence (prose and example requests) to use the versioned path "/v1/context" so examples like the endpoint URL and the documented operation (e.g., "PUT /context") consistently read "PUT /v1/context" and the sample URL shows "https://your-subdomain.absmartly.io/v1/context".
67-89:⚠️ Potential issue | 🟠 MajorThe sample timestamps do not match the documented payload shape.
Lines 69 and 79 use
{{ticket.created_at_with_timestamp}}forpublishedAtandachievedAt, while the reference section later describes both fields as Unix millisecond timestamps. If Zendesk renders that placeholder as a timestamp string, the example is both invalid JSON when left unquoted and the wrong type for the ABsmartly payload, so the guide needs either a Zendesk-safe milliseconds value or a note that an intermediary transform is required.Verify Zendesk's `{{ticket.created_at_with_timestamp}}` placeholder output format and whether Zendesk webhooks can emit Unix-millisecond values directly; also verify the ABsmartly Collector API types for `publishedAt` and `goals[].achievedAt`.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/Third-party-integrations/Zendesk-Integration.mdx` around lines 67 - 89, The sample uses Zendesk placeholder {{ticket.created_at_with_timestamp}} unquoted for publishedAt and goals[].achievedAt which may render as a string and break ABsmartly's Unix-millisecond typed fields; verify Zendesk's placeholder output and ABsmartly Collector API types, then update the example in the Zendesk-Integration doc so publishedAt and goals[].achievedAt are valid Unix millisecond numbers (or quote them and add a clear note that an intermediary transform is required), referencing the JSON fields publishedAt and goals[].achievedAt and the Zendesk placeholder {{ticket.created_at_with_timestamp}} so the payload matches the Collector API types.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/Third-party-integrations/Zendesk-Integration.mdx`:
- Around line 30-31: The guide inconsistently references the collector endpoint
as both "/context" and "/v1/context"; update every occurrence (prose and example
requests) to use the versioned path "/v1/context" so examples like the endpoint
URL and the documented operation (e.g., "PUT /context") consistently read "PUT
/v1/context" and the sample URL shows
"https://your-subdomain.absmartly.io/v1/context".
- Around line 67-89: The sample uses Zendesk placeholder
{{ticket.created_at_with_timestamp}} unquoted for publishedAt and
goals[].achievedAt which may render as a string and break ABsmartly's
Unix-millisecond typed fields; verify Zendesk's placeholder output and ABsmartly
Collector API types, then update the example in the Zendesk-Integration doc so
publishedAt and goals[].achievedAt are valid Unix millisecond numbers (or quote
them and add a clear note that an intermediary transform is required),
referencing the JSON fields publishedAt and goals[].achievedAt and the Zendesk
placeholder {{ticket.created_at_with_timestamp}} so the payload matches the
Collector API types.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 41955536-39f8-4ae6-b75a-194995a14237
📒 Files selected for processing (1)
docs/Third-party-integrations/Zendesk-Integration.mdx
3 participants
Summary
Summary by CodeRabbit