Overdesk Docs

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 never a dependency: the scheduled checks keep running either way.

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. Zendesk and Intercom events carry none, so on those two set Allowed inboxes to all (or Zendesk:all and Intercom:all alongside another help desk).

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 deskWhere the secret comes from
Help ScoutHelp Scout asks you to invent one, so Overdesk generates it for you
ZendeskZendesk generates it and shows it to you
IntercomIntercom generates it and shows it to you
FreeScoutFreeScout 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 ​

  1. In Settings → Developers, find the Help Scout card and choose Copy next to the Endpoint URL.
  2. Choose Generate a secret. Overdesk starts using it straight away and shows it once, under Your new signing secret, shown once. Copy it.
  3. In Help Scout, create a webhook. Paste the endpoint URL as its address, paste the secret into its secret key field, select the event for new conversations, and save.

The endpoint URL is not the Redirection URL you entered when you created the Help Scout app.

Zendesk ​

  1. In Settings → Developers, copy the Endpoint URL from the Zendesk card.
  2. 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.
  3. Zendesk shows the webhook's 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.

Intercom ​

  1. In Settings → Developers, copy the Endpoint URL from the Intercom card.
  2. In Intercom's Developer Hub, open your app's webhook settings, paste the endpoint URL, and subscribe to the topics conversation.user.created and conversation.user.replied.
  3. Copy the signing secret Intercom shows you into Signing secret on the Intercom card, and choose Save.

FreeScout ​

  1. In FreeScout, open Manage, then Settings, then API & Webhooks, and copy the Secret Key.
  2. In Settings → Developers, paste it into Signing secret on the FreeScout card and choose Save. Copy the card's Endpoint URL while you are there.
  3. Back on the API & Webhooks page in FreeScout, add a webhook pointing at the endpoint URL, for new conversations and for customer replies.

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. Replies from your own agents never do, so a draft Overdesk posts can never come back to it as a new event.

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 Help Scout straight away.
  • 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.