Skip to content

docs: add Zendesk webhook integration guide #253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chris-absmartly merged 2 commits into from
Mar 9, 2026
Merged

docs: add Zendesk webhook integration guide #253

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b2d57d5
docs: add Zendesk webhook integration guide
joalves Mar 9, 2026
c229118
Update docs/Third-party-integrations/Zendesk-Integration.mdx
chris-absmartly Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 153 additions & 0 deletions docs/Third-party-integrations/Zendesk-Integration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
---
sidebar_position: 4
---

import Admonition from "@theme/Admonition";

# Zendesk Integration

This guide explains how to send Zendesk support ticket events as goal events to ABsmartly
using [Zendesk Webhooks](https://support.zendesk.com/hc/en-us/articles/4408839108378-Creating-webhooks-to-interact-with-third-party-systems).
This allows you to track support ticket creation as a metric in your experiments — for example,
to measure whether a new feature reduces or increases support requests.

## Prerequisites

1. **ABsmartly account** with access to the Web Console and a valid **SDK API Key**.
API Keys can be created under `Settings > API Keys` in the ABsmartly Web Console.
2. **Zendesk account** with Admin access to create webhooks and triggers.
3. A **unit type** (e.g. `user_id` or `email`) that is shared between your ABsmartly
experiments and your Zendesk tickets so that events can be attributed to the correct user.

## Step 1 — Create a Webhook in Zendesk

1. In Zendesk, go to **Admin Center > Apps and integrations > Webhooks > Webhooks**.
2. Click **Create webhook**.
3. Select **Trigger or automation** as the connection method and click **Next**.
4. Fill in the webhook details:
- **Name**: `ABsmartly Goal Event`
- **Description**: `Sends ticket events to ABsmartly as goal events`
- **Endpoint URL**: Your ABsmartly Collector endpoint followed by `/context`.
For example: `https://your-subdomain.absmartly.io/v1/context`
Comment on lines +30 to +31
Copy link

@coderabbitai coderabbitai bot Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

cat -n docs/Third-party-integrations/Zendesk-Integration.mdx | head -40

Repository: 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 with type and uid [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: ok plus optional warnings[] / errors[] entries (each includes batchIndex, 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:

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.

- **Request method**: `PUT`
- **Request format**: `JSON`
5. Under **Authentication**, select **API key** and configure it:
- **Header name**: `X-API-Key`
- **Value**: Your ABsmartly SDK API Key
6. Add the following **custom headers**:

| Header name | Value |
| --- | --- |
| `X-Application` | The application name matching your ABsmartly Web Console (e.g. `www`) |
| `X-Application-Version` | `0` |
| `X-Environment` | The environment name matching your ABsmartly Web Console (e.g. `production`) |
| `X-Agent` | `zendesk-webhook` |

7. Click **Create webhook**.

<Admonition type="info">
The <code>X-Application</code> and <code>X-Environment</code> values must match
existing entries in your ABsmartly Web Console under <code>Settings &gt; Applications</code>
and <code>Settings &gt; Environments</code>.
</Admonition>

## Step 2 — Create a Trigger to Send the Webhook

1. In Zendesk, go to **Admin Center > Objects and rules > Business rules > Triggers**.
2. Click **Create trigger**.
3. Give the trigger a name, for example: `Send ticket to ABsmartly`.
4. Under **Conditions**, configure when the trigger should fire. For example, to fire
on every new ticket:
- **Meet ALL of the following conditions**:
- `Ticket > Is > Created`
5. Under **Actions**, select **Notify webhook** and choose the `ABsmartly Goal Event`
webhook you created in Step 1.
6. In the **JSON body** field, enter the following payload:

```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}}"
}
}
]
}
```
Comment on lines +67 to +89
Copy link

@coderabbitai coderabbitai bot Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

find . -type f -name "*Zendesk*" | head -20

Repository: absmartly/docs

Length of output: 113

🏁 Script executed:

git ls-files | grep -i zendesk | head -20

Repository: absmartly/docs

Length of output: 111

🏁 Script executed:

git ls-files docs/Third-party-integrations/ | head -30

Repository: 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.


7. Click **Save**.

<Admonition type="tip">
Adjust the <code>units</code> type and value to match the unit type you use in your
ABsmartly experiments. For example, if your experiments use a <code>user_id</code> unit,
you may need to use a custom Zendesk user field that contains the user ID instead of
the email address.
</Admonition>

## Step 3 — Create the Goal in ABsmartly

1. In the ABsmartly Web Console, go to **Settings > Goals**.
2. Create a new goal named `zendesk_ticket_created` (matching the `name` in the webhook payload).
3. You can now use this goal to create metrics.

## Payload Reference

The webhook payload follows the [ABsmartly Collector API](/docs/APIs-and-SDKs/SDK-API/context-publish)
`PUT /context` format. Here is a summary of the key fields:

| Field | Description |
| --- | --- |
| `publishedAt` | Timestamp (Unix ms) of when the event was sent |
| `units` | Array of unit objects identifying the user. Each has a `type` and `uid` |
| `goals` | Array of goal objects. Each has a `name`, `achievedAt` timestamp, and optional `properties` |

### Available Zendesk Placeholders

You can use [Zendesk placeholders](https://support.zendesk.com/hc/en-us/articles/4408886858138-Zendesk-Support-placeholders-reference)
in the webhook payload to dynamically include ticket data. Some useful ones:

| Placeholder | Description |
| --- | --- |
| `{{ticket.id}}` | The ticket ID |
| `{{ticket.title}}` | The ticket subject |
| `{{ticket.requester.email}}` | The requester's email address |
| `{{ticket.requester.name}}` | The requester's name |
| `{{ticket.priority}}` | The ticket priority |
| `{{ticket.via}}` | The channel the ticket came from |
| `{{ticket.created_at_with_timestamp}}` | Ticket creation timestamp |

## Tracking Different Ticket Events

You can create multiple triggers to track different types of ticket events as separate goals.
For example:

- **Ticket solved** — Create a trigger with the condition `Ticket > Status > Changed to > Solved`
and set the goal name to `zendesk_ticket_solved`.
- **High-priority ticket** — Create a trigger with the condition `Ticket > Priority > Is > Urgent`
and set the goal name to `zendesk_urgent_ticket_created`.

## Verifying the Integration

1. Create a test ticket in Zendesk from a user whose identifier (e.g. email) is also
being tracked in an ABsmartly experiment.
2. Check the ABsmartly Web Console under the experiment's goals to verify
that the `zendesk_ticket_created` event was received.
3. You can also check the webhook activity in Zendesk under
**Admin Center > Apps and integrations > Webhooks** by clicking on your webhook
and viewing the **Activity** tab.

If you have any issues setting up the Zendesk integration, please contact us at
[support@absmartly.com](mailto:support@absmartly.com).