Skip to content

Developers ​

The Developers tab holds the webhooks that connect Overdesk to other systems. Webhooks are what your help desk needs to send Overdesk real-time updates: a webhook endpoint address and a signing secret for each help desk you have connected. Without a webhook, Overdesk syncs on a schedule. With one, it reacts the moment a conversation is created or updated. The Finding webhook works the other way: Overdesk sends your own endpoint each finding as it opens, comes back or changes. See Finding webhook. API keys let a script or one of your own tools call Overdesk without signing in; see API keys.

Open Settings → Developers. The tab is visible to owners and admins. Saving or generating a signing secret, and adding or testing the finding webhook, are included in the Pro and Scale plans and in the trial; see Plans and pricing.

What the tab shows ​

Under Webhooks there is one card for each connected help desk. If no help desk is connected yet, the tab says so: connect one first from Integrations, and its card appears here.

Each card shows:

  • Whether the webhook is Configured or Not configured.
  • The Endpoint URL, with a Copy button. This is the address you paste into your help desk's webhook settings, where some help desks call it the callback or payload URL. It is not a Help Scout app's Redirection URL.
  • Once configured, how many events have arrived and when the last one came in.
  • The Signing secret field, with Save and, once a secret is stored, Remove.

Setting the signing secret ​

The signing secret proves that an event really came from your help desk. Which side creates it depends on the help desk.

Help deskWho creates the secretWhat you do
Help ScoutYou. Help Scout asks you to invent one.Click Generate a secret on the Help Scout card. Copy the secret it shows, then paste it into the secret field of your webhook in Help Scout and save there.
ZendeskZendesk, when you create the webhook.Open the webhook by its name in Zendesk's Admin Center, choose "Reveal secret", paste it into Signing secret and click Save.
IntercomIntercom: it is your app's "Client secret".Copy the "Client secret" from your app's "Basic information" page in Intercom's Developer Hub, paste it into Signing secret and click Save.
FreeScoutFreeScout.Paste FreeScout's secret into Signing secret and click Save, then connect FreeScout again from Integrations. Overdesk registers the webhook on your FreeScout for you.

A generated secret is shown once. Overdesk starts using it immediately, so paste it into your help desk before you leave the page, or events will arrive unsigned and be rejected.

A secret needs at least 16 characters, and it must never contain any part of the endpoint URL: anyone who has seen that address could then forge events. Overdesk refuses a secret that breaks either rule, and warns you on the card if the stored one is too easy to guess.

For the steps inside each help desk, see Real-time updates with webhooks.

Replacing or removing a secret ​

On the Help Scout card, Replace with a new secret issues a fresh one. Overdesk verifies against the new secret straight away, and the old one stops working the moment you continue, so every event Help Scout sends is rejected until you paste the new secret into the webhook there too. The webhook that @Overdesk in notes adds follows by itself; if Help Scout refuses the change, the card says so, and turning @Overdesk off and on reconnects it.

Remove deletes the stored secret. Overdesk stops accepting real-time events from that help desk and falls back to scheduled syncing. Removing a secret works on every plan. On Help Scout it also turns @Overdesk in notes off.

What Overdesk checks ​

Every event is signature-verified before Overdesk accepts it, and an unsigned or mismatched event is rejected. Scheduled syncing keeps running alongside webhooks as a safety net, so a webhook speeds Overdesk up and is never something it depends on.

Real-time drafts follow the same Allowed inboxes setting as scheduled ones. See Allowed inboxes.

Finding webhook ​

The finding webhook lets another system, such as your own tooling or an AI agent, act on what the analyses find without anyone checking the dashboard. Overdesk sends it a signed request each time a finding opens, comes back after it was resolved or dismissed, or changes status because a person decided on it or Overdesk resolved it on its own.

A finding getting more severe is not sent. Each finding stays one finding while its conversations grow, so your system hears about it once when it opens, not on every run.

Adding it ​

  1. Under Finding webhook, enter your endpoint's address in Endpoint URL and click Add webhook. The address must start with https://. Overdesk will not send to an address on a private or internal network, and refuses one with sign-in details written into it.
  2. Overdesk creates a signing secret and shows it once, under Your signing secret, shown once. Copy it into your endpoint's configuration before you leave the page. Overdesk never shows it again.
  3. Click Send a test. Overdesk sends a test event straight away and tells you what your endpoint answered.

Save address changes the address and keeps the secret, so your endpoint's check keeps working. To get a new secret, Remove the webhook and add it again. Removing it stops every delivery, including any waiting to be retried, and works on every plan.

Only a signed-in owner or admin can see, add, change, test or remove the finding webhook. An API key cannot: every change carries the name of the person who made it, and the address can hold your endpoint's own token.

What each request carries ​

Each request is a POST with a JSON body:

json
{
  "id": "5f0c3b2e-8a41-4c7e-9d2a-0b6e1f3a7c55",
  "event": "finding.status_changed",
  "occurred_at": "2026-09-24T09:12:03Z",
  "sent_at": "2026-09-24T09:12:04Z",
  "status": "resolved",
  "changed_by": "person",
  "finding": { "id": "…", "title": "…", "summary": "…", "severity": "high", "status": "resolved", "url": "…", "evidence": [] }
}

The fields:

text
id           The delivery. The same on every retry, so use it to ignore a repeat.
event        finding.opened, finding.reopened, finding.status_changed or test.
occurred_at  When it happened. sent_at is when this request was sent.
status       With finding.status_changed: the status the finding moved to.
changed_by   With finding.status_changed: person or overdesk.
finding      The finding as it stands when the request is sent. Absent on a test.

The finding:

text
id                 The finding. The same in every event about it.
producer           The analysis that found it, for example spike or churn_signals.
kind               What sort of issue it is, for example regression or frustration.
title              Its name, fixed when it was first found.
summary            The latest run's description of it.
product            The product it concerns, when the analysis named one.
severity           critical, high, medium or low.
status             open, acknowledged, resolved or dismissed.
status_changed_at  When its status last changed.
first_seen         When an analysis first reported it.
last_seen          When an analysis last reported it.
seen_count         How many runs have reported it.
tickets            How many conversations it has cited.
confirmed          On a confirmed defect, how many of its conversations are
                   confirmed, and suspected, how many only look like the same
                   defect. Absent on every other finding.
trend              new, worsening or steady.
url                The finding in Overdesk.
evidence           Its conversations, most recently cited first: provider,
                   conversation_id, number, first_seen, last_seen, and
                   ticket_url, the conversation in your help desk. On a
                   confirmed defect each one also has level, confirmed or
                   suspected.

A finding never quotes a customer, and shows (a customer) wherever the analysis named someone. See Intelligence.

Requests about one finding can arrive in a different order from the events, because a delivery that failed is retried later while the next one goes out. Every request carries the finding as it is when sent, so treat its status as the current one rather than working it out from the order of events.

Checking the signature ​

Each request carries four headers:

HeaderWhat it holds
X-Overdesk-EventThe event, such as finding.opened
X-Overdesk-DeliveryThe delivery's id
X-Overdesk-TimestampWhen it was sent, as a Unix time in seconds
X-Overdesk-Signaturesha256= followed by the signature

The signature is an HMAC-SHA256 of the timestamp, a full stop and the raw request body, keyed with your signing secret and written as lowercase hex. To check a request, compute the same value and compare it with the header, and reject a request whose timestamp is more than a few minutes old. In Python:

python
import hashlib, hmac

def is_from_overdesk(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + expected, signature)

With the secret test-secret, the timestamp 1700000000 and the body {"id":"x"}, the signature is sha256=bcadb3a3ee7633fd9db6910d1ec0801c2ad9c7d064479c5e574c5fffccd4b39f.

When your endpoint does not answer ​

Your endpoint has 10 seconds to answer, and any success status counts as delivered. Anything else, including a redirect, which Overdesk does not follow, means Overdesk tries again: after a minute, then 5 minutes, 30 minutes, 2 hours and 6 hours. After the sixth try it gives up on that event. The card under Finding webhook says when the last delivery was made and what your endpoint answered, and when Overdesk gives up on an event it raises an alert on the Alerts page, once until someone acknowledges it. See Alerts.

If your system misses events, it can catch up from GET /api/v1/findings with an API key, which lists every finding whatever was delivered. A finding whose conversations were all erased is deleted without an event and leaves that list too. See Erasure and deletion requests.

On a plan without the finding webhook, nothing is sent until the plan includes it again. The webhook stays, so you can still see it or remove it.

API keys ​

An API key lets a script or one of your own tools call the Overdesk API without signing in. A signed-in owner or admin creates one under API keys: give it a Name and a Role, and copy the key when it is shown. A key's role is capped at your own, and no key acts as an owner. Send it in an X-API-Key header.

A key can read whatever its role can read. Beyond reading, it can:

  • generate a report and run an analysis
  • ask for a draft of one conversation, which waits for a person to review it
  • re-sync a knowledge source you have already added
  • send feedback to Overdesk, and send a test notification to the channels you have set up

Everything else that changes your workspace needs someone signed in to Overdesk, whatever role the key has, and whether or not your workspace sends replies automatically. That covers settings, the send mode, rules, prompts and excluded senders; knowledge sources, integrations and webhooks; schedules and running jobs; and editing, sending or discarding a draft. A key also cannot start connecting an integration or open the Google Docs picker. A key that tries is refused with 403 and the message this action requires a logged-in user, not an API key.

This is so a key that leaks cannot change what your replies say or whether they go out.