Connect Zendesk
Connect Zendesk with an OAuth client, then add a webhook and a trigger in Zendesk. Tickets come in by themselves, and approved replies go back to Zendesk.
If your support tickets live in Zendesk, connect it directly. No code is needed. Zendesk tells us when a ticket is created or updated. We read the ticket from Zendesk, signed in with an OAuth client you make in Zendesk. Approved replies go back into Zendesk.
Each platform connects one ticket system. See Connect your ticket system for how that works.
Before you start#
You need a Zendesk admin. Only an admin can make an OAuth client, a webhook and a trigger.
Replies and notes show in Zendesk as written by the admin who makes the OAuth client. If you want them to show a name of their own, first make a Zendesk admin for the AI, such as one named "Cerberius Agent", and sign in to Zendesk as them to make the client. It must be able to see the tickets this platform takes.
Why not an API token?
Zendesk is retiring API tokens. Since 27 October 2026 nobody can make a new one, and on 30 April 2027 every API token stops working. An OAuth client is what Zendesk now recommends.
Connect Zendesk#
- 1
In Zendesk, make an OAuth client. Open Admin Center, go to Apps and integrations › APIs › OAuth clients, and click Add OAuth client.
- 2
Give it a Name, such as "Cerberius Agents". Set Client kind to Confidential. Leave Scopes empty. We don't use Redirect URLs: leave it empty, or if Zendesk asks for one, enter your Zendesk address.
- 3
Click Save. A Secret shows lower on the page. Copy all of it: Zendesk shows it in full only once, and it may run past the end of the box. Then click Save again. Note the client's Identifier too.
- 4
Here, go to Settings › Ticket system. On the Connection tab, click Connect a ticket system and choose Zendesk.
- 5
Under Your Zendesk, fill in the Zendesk address, the Unique identifier (the client's Identifier) and the Secret. Show me how on our page shows the Zendesk steps too.
- 6
Choose how Approved replies go back, what happens After a reply, and whether to add the Agent's findings in Zendesk.
- 7
Click Connect Zendesk. Then click Check connection.
- 8
Under Which organisations, tick the Zendesk organisations whose tickets this platform takes, or leave them all unticked to take every ticket. Click Save.
Then tell Zendesk about new tickets, as below. Until you do, no tickets come in.
| Setting | What it does |
|---|---|
| Zendesk address | The address you open Zendesk at, for example https://yourcompany.zendesk.com. You can also type just yourcompany. Only a zendesk.com address is accepted, so your secret only ever goes to Zendesk. |
| Unique identifier | The OAuth client's Identifier in Zendesk. |
| Secret | The OAuth client's Secret. Once saved, it is never shown again. Type a new one to replace it. |
| Check connection | Shows once Zendesk is connected. It signs in to Zendesk with the client, and says whether that worked and whose name replies will show. The client must be made by a Zendesk agent or admin. |
| Webhook address | Shows once Zendesk is connected, with Copy. You paste it into Zendesk. Keep it private. |
| Zendesk's signing secret | Zendesk signs every call it makes with a secret of its own. Paste it here once the webhook is made. We then refuse calls without Zendesk's signature, or sent more than 5 minutes before they reach us. Until you paste it, the page warns that calls aren't checked. Paste a new one replaces it; Remove it stops the check. |
| Last heard from Zendesk | When Zendesk last called the webhook address. Never yet means it hasn't called: check the steps. If a call was refused, it says when and why, such as wrong signature. |
| The trigger's JSON body | Shows once Zendesk is connected, with Copy. You paste it into the trigger in Zendesk. Only the ticket's number is used: we read everything else from Zendesk ourselves. |
| Which organisations | Shows once Zendesk is connected: your Zendesk organisations, read from Zendesk. Tick the ones whose tickets come to this platform, the customers whose systems this platform can look into. With none ticked, every ticket comes here. With some ticked, a ticket with no organisation doesn't come here. An organisation that another of your platforms takes from the same Zendesk can't be ticked, and says which platform takes it. Tickets already here stay here. |
| Approved replies | Add it as a public reply: Zendesk sends it to the requester straight away, as from the admin who made the OAuth client. Add it as a private note: your team reads it in Zendesk and sends it themselves. |
| After a reply | Then set its status to: Open, Pending, On-hold or Solved, or Leave it as it is. For example, Pending shows you are waiting for the requester. It only changes once nothing else on the ticket waits here, such as a fix. If Zendesk refuses the change, the reply still counts as sent. Off at first. |
| Agent's findings in Zendesk | When on, a private note with what the agent found goes on the Zendesk ticket as soon as a reply is ready to approve. Only your Zendesk team sees it. Off at first. |
Once Zendesk is connected, change anything here and click Save at the bottom.
If the admin who made the OAuth client stops being an admin, or leaves, Zendesk stops taking the client. Make a new client and save its identifier and secret here.
Let Zendesk tell us about tickets#
Zendesk tells us about tickets through a webhook (our address, which Zendesk calls) and a trigger (a rule in Zendesk that calls it). You set both up once, in Zendesk's Admin Center. Our page shows the same steps under Let Zendesk tell us about tickets.
- 1
Make the webhook. Go to Apps and integrations › Webhooks › Webhooks and click Create webhook. Choose Trigger or automation, then click Next.
- 2
Give it a Name, such as "Cerberius Agents". Paste the Webhook address from our page as the Endpoint URL. Set Request method to POST, Request format to JSON, and Authentication to None required. Click Create webhook.
- 3
Make the trigger. Go to Objects and rules › Business rules › Triggers and click Create trigger. Give it a Name, such as "Tell Cerberius Agents".
- 4
Under Conditions, add two conditions that meet Any of them: Ticket › Ticket Is Created, and Ticket › Ticket Is Updated.
- 5
Under Actions, click Add action and choose Notify by › Active webhook. Pick the webhook you made. Paste The trigger's JSON body from our page as the body. Click Create trigger.
- 6
If Zendesk asked you to connect the webhook to a trigger, go back to the webhook and click Finish setup.
- 7
Copy the signing secret. Open the webhook again (Apps and integrations › Webhooks › Webhooks), and click Reveal secret under Signing secret. Copy it, and paste it into Zendesk's signing secret on our page. Click Save the secret.
- 8
Try it. Create a test ticket. It shows under Tickets here within a minute, and our page says Last heard from Zendesk with the time.
To send only some tickets, add more conditions to the trigger, under All. For example, only tickets of one brand or one group.
What happens with a Zendesk ticket#
- A new ticket in Zendesk reaches the agent, with its files. Who asked comes from Zendesk's own record of that person, never from what the ticket says.
- A public reply from the requester in Zendesk reaches the agent as a follow-up. Your team's replies and private notes are skipped.
- Solving or closing it in Zendesk stops the work on it here.
- Closing it here sets it to Solved in Zendesk. Zendesk closes solved tickets by itself later.
- A closed Zendesk ticket can't take a reply: Zendesk doesn't allow it. The reply here says it failed. In Zendesk, create a follow-up for the ticket and reply there.
Only tickets that came from Zendesk go back to Zendesk. Other tickets on the same platform, from the log watcher for example, don't.
Tickets opened in Zendesk before you connected don't come in by themselves. Importing older tickets works for Halo only for now.
One Zendesk, a platform per customer
An IT company often runs one Zendesk for all its customers, and each customer's systems are their own platform. Connect each customer's platform to the same Zendesk, and under Which organisations tick that customer's organisation. Each platform has its own Webhook address: make a webhook and a trigger in Zendesk for each one. Two platforms never take the same organisation's tickets.
Stop#
Click Disconnect… at the top of the Connection tab, and confirm. New tickets from Zendesk stop coming in, and replies stop going back to it. The webhook address stops working at once. Tickets already here stay.
Then, in Zendesk, delete the trigger and the webhook, and delete the OAuth client under Apps and integrations › APIs › OAuth clients.