Appearance
Real-time updates with webhooks
Out of the box, Overdesk checks your help desk on a schedule and drafts on a 15-minute cycle. A webhook lets your help desk tell Overdesk the moment a conversation arrives, so its draft is waiting before an agent opens it. Webhooks are a speed-up, and the scheduled checks keep running either way. The one thing that needs a webhook, on all four help desks, is asking Overdesk in an internal note, because a note is not something the scheduled checks look for. See Ask Overdesk in a note. On Help Scout, one switch sets that webhook up for you.
Before you start
- Webhooks are part of the trial, Pro and Scale. On Assist, saving a signing secret is refused, with a message that webhooks are not part of your plan and a pointer to Billing.
- You need to be an owner or admin. The webhook settings live in Settings → Developers, under Webhooks, with one card per connected help desk.
- A real-time draft still follows Allowed inboxes. Help Scout and FreeScout events carry the mailbox, so a list of mailbox numbers works. Before drafting, Overdesk checks the inbox again on the conversation itself, as your help desk reports it, so a conversation that is not in an allowed inbox gets no real-time draft. Zendesk events carry none, so on Zendesk set Allowed inboxes to
all(orZendesk:allalongside another help desk). Intercom events carry none either, but Overdesk reads the conversation's team before drafting, soIntercom:and a team's id works in real time too.
How the signing secret works
Every event is signed, and Overdesk verifies the signature before it accepts anything. An unsigned or mismatched event is rejected. Who creates the secret depends on your help desk:
| Help desk | Where the secret comes from |
|---|---|
| Help Scout | Help Scout asks you to invent one, so Overdesk generates it for you |
| Zendesk | Zendesk generates it, and shows it on the webhook's own page in Admin Center |
| Intercom | It is your Intercom app's "Client secret", on the app's "Basic information" page in the Developer Hub |
| FreeScout | FreeScout shows it to you, on the same page as its API key |
Never use any part of the endpoint URL as the secret. Everyone who has seen that URL could then forge events, so Overdesk refuses one. A secret you paste needs at least 16 characters.
Help Scout
Ask Overdesk in a note: one switch
On Integrations, open Help Scout and turn on @Overdesk in notes. Overdesk adds a webhook named "Overdesk @mentions" to your Help Scout that sends internal notes and nothing else, signed with a key derived from your signing secret. If you have no signing secret yet, Overdesk makes one.
- Turning the switch on is part of the trial, Pro and Scale, and needs an owner or admin. Turning it off works on every plan.
- Off deletes that one webhook and nothing else. Disconnecting Help Scout deletes it too, and so does connecting again with a different App ID, or connecting in one click to a different Help Scout account.
- If the webhook you added to Help Scout for Overdesk already has "Conversation Note Added" ticked, Overdesk already answers your notes, and the switch tells you so rather than adding a second webhook. To let Overdesk manage it, untick that event on your webhook and turn the switch on.
- If Help Scout switches the webhook off after failed deliveries, or someone deletes it there, the switch shows it. Turn it on again to reconnect it.
The switch never drafts. For real-time drafts, add your own webhook as below.
Real-time drafting: your own webhook
- In Settings → Developers, find the Help Scout card and choose Copy next to the Endpoint URL.
- Choose Generate a secret. Overdesk starts using it straight away and shows it once, under Your new signing secret, shown once. Copy it.
- In Help Scout, open the "Webhooks" app from its "Apps" section. Paste the endpoint URL into "Callback URL" and the secret into "Secret Key", tick the events you want and the inboxes Overdesk drafts in, and save:
- "Conversation Note Added", to ask Overdesk in an internal note, only if you don't use the switch above. With both, every note is read twice.
- "Conversation Created", to draft as soon as a conversation arrives. On a workspace that has turned sending on, the replies your guardrails approve then go out as soon as they are written, rather than on the next scheduled check.
- "Customer Reply" (
convo.customer.reply.created), to draft as soon as a customer writes back on a conversation. A real-time draft follows the same rules as a scheduled one, including the notes and sending behaviour above.
The endpoint URL is not the Redirection URL you entered when you created the Help Scout app.
Zendesk
- In Settings → Developers, copy the Endpoint URL from the Zendesk card.
- In Zendesk's Admin Center, create a webhook that subscribes to Zendesk events, with the endpoint URL as its address. Select the events for a ticket being created and a comment being added.
- In Admin Center's list of webhooks, click the webhook's name rather than "Edit", and choose "Reveal secret" under "Signing secret". Paste it into Signing secret on the Zendesk card and choose Save.
A comment triggers a draft only when it is public and written by the customer, so your agents' own replies and notes never set one off.
The same webhook delivers your agents' internal notes, so asking @Overdesk in a note needs nothing more. A note is read only for @Overdesk, and Overdesk answers it with a note of its own. A note never starts a draft.
Intercom
- In Settings → Developers, copy the Endpoint URL from the Intercom card.
- In Intercom's Developer Hub, open your app's webhook settings, paste the endpoint URL, and subscribe to the topics
conversation.user.createdandconversation.user.replied. To ask Overdesk in a note, subscribe toconversation.admin.notedas well. It is the topic Intercom sends when a teammate adds a note, and without it Overdesk never sees one. - Intercom signs every webhook with your app's "Client secret". Copy it from the app's "Basic information" page into Signing secret on the Intercom card, and choose Save. Do this before you choose "Send a test request" in Intercom: until the secret is saved, Overdesk refuses the test and Intercom reports it as unsuccessful.
A note is read only for @Overdesk, and Overdesk answers it with a note of its own. A note never starts a draft.
FreeScout
- In FreeScout, open Manage, then Settings, then API & Webhooks, and copy the Secret Key.
- In Settings → Developers, paste it into Signing secret on the FreeScout card and choose Save.
- Connect FreeScout again from its page on Integrations. Overdesk then adds its own webhook to your instance, for new conversations, customer replies and internal notes, so you don't add one by hand.
FreeScout signs every webhook with that Secret Key, and Overdesk checks each event against the copy you saved. Only new conversations and customer replies start a draft. A note is read only for @Overdesk, and Overdesk answers it with a note of its own. Only a note a person types in the FreeScout web app, or sends by email, counts: a note another app adds through the API does not ask. Replies from your own agents never start anything, so a draft Overdesk posts can never come back to it as a new event.
If you connected FreeScout before notes were included, connect it again once to add them.
Checking it works
A card with a stored secret reads Configured and shows how many events have arrived and when the last one came in, or No events received yet. If a secret is too easy to guess, the card says so and tells you how to replace it.
Replacing or removing a secret
- On Help Scout, Replace with a new secret issues a fresh one. The old one stops working at once, so paste the new one into your own Help Scout webhook straight away. The @Overdesk webhook follows by itself, and if Help Scout refuses the change, the card says so: turn @Overdesk off and on to reconnect it.
- On the others, paste the new secret from your help desk into Signing secret and save.
- Remove deletes the secret. Overdesk stops accepting real-time events for that help desk and goes back to its scheduled checks. On Help Scout it also turns @Overdesk in notes off.