Webhooks send ticket events from your organization to a URL you control. When something happens in initdesk—a new ticket, a reply, a status change—initdesk POSTs a JSON payload to your endpoint so you can log it, sync another system, or run automation.

This is separate from Slack (see Connecting Slack notifications), email/web push alerts, and the public API. Use webhooks when you want initdesk to push events to your server.

---

Before you start

You need:

• Permission to open Settings for the organization
• An HTTPS endpoint that accepts POST with a JSON body
• A way to inspect incoming requests (server logs, a staging receiver, or a temporary request bin)

Respond with an HTTP 2xx status as soon as you have accepted the payload. initdesk waits up to 15 seconds for your response.

---

Create a webhook

1. Switch to the organization you want to configure.
2. Go to Settings → Webhooks.
3. Create a webhook and paste your endpoint URL.
4. Choose a template:
   • Default (integration) — JSON for your own systems (recommended for most integrations).
   • Slack — Slack Block Kit payload for a Slack incoming webhook URL. Prefer the Slack plugin if you want channel mapping and OAuth; use this template only when you already have a Slack incoming webhook URL.
5. Select the events you want to receive (you can change this later).
6. Optionally add a short description so teammates know what the endpoint is for.
7. Save.

Then trigger a real action in initdesk (for example create a test ticket if you subscribed to ticket.created) and confirm your server received the POST.

---

How delivery works

For every matching webhook, initdesk:

1. Builds the payload after the ticket change is committed in the database (so you never see a half-saved ticket).
2. Sends an HTTP POST to your endpoint_url with Content-Type: application/json.
3. Treats the delivery as successful only when your endpoint returns an HTTP 2xx status.
4. On failure (timeout, network error, or any 4xx / 5xx response), retries automatically with exponential backoff, up to 10 retries after the first attempt.

You do not need to ask initdesk to retry. Make your handler idempotent: the same event may be delivered more than once if an earlier attempt timed out or returned an error after you already processed it.

Timeouts

Your endpoint must respond within 15 seconds. Do heavy work asynchronously after you return 2xx.

Delivery logs

initdesk keeps short-lived delivery logs (status code and response body) for about 24 hours for troubleshooting. They are not a long-term audit trail—store what you need on your side.

---

Events you can subscribe to

Subscribe only to the events you need. Available events:

Message events fire when a new message is saved (not for imported historical messages).

---

Default payload shape

With the Default (integration) template, the body looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20{
  "event": "ticket.created",
  "data": {
    "id": 12345,
    "public_id": "42",
    "subject": "Cannot reset my password",
    "status": "created",
    "waiting_on": "associate",
    "tags": ["billing"],
    "customer": {
      "name": "Alex Example",
      "email": "alex@example.com"
    },
    "assignee": null,
    "inbox": {
      "id": 1,
      "name": "Main Inbox"
    }
  }
}

• event is the event name you subscribed to.
• data is the full ticket detail snapshot at send time (same shape as the ticket detail API: subject, status, customer, assignee, tags, inbox, channel, timestamps, and related fields).

Always read event first, then inspect data. Field contents can grow over time; ignore unknown fields safely.

The Slack template sends Slack blocks instead of this { "event", "data" } envelope. Use Default for custom code.

---

Security

initdesk currently sends webhooks without a cryptographic signature header. Treat your endpoint as a public ingress and harden it yourself:

• Prefer HTTPS only.
• Use a long, unguessable path or query token in the URL (for example https://hooks.example.com/initdesk/a8f3…) and reject requests that omit it.
• Process asynchronously after returning 2xx so retries do not pile up work on a slow handler.

Do not put secrets in ticket fields that will be echoed back in the payload.

---

Tips

• Start in staging with a request inspector, then point the same webhook at production once parsing is stable.
• Prefer narrow event lists—especially avoid ticket.internal_note_created if the receiver should not see private notes.
• For Slack channel alerts with inbox routing, use the Slack plugin instead of a raw Slack webhook URL when you can.
• If deliveries fail, check that your endpoint returns 2xx within 15 seconds and that the URL is reachable from the public internet.

---

Frequently asked questions

Does initdesk retry failed deliveries?
Yes. Timeouts, network errors, and non-2xx responses are retried with backoff (up to 10 retries after the first attempt).

Should my server also implement retries toward initdesk?
No. Return 2xx when you accept the event, and make handling idempotent so duplicate deliveries are safe.

Is there a signing secret in Settings?
No. There is no webhook signing key today. Authenticate with a secret URL token or other controls on your side.

Will I get one request per event per webhook?
Yes. Each webhook you configure that includes the event receives its own POST.

Can I delay delivery?
Not from Settings. Events are queued as soon as the ticket change is committed.

Does this replace the API or MCP?
No. Webhooks push events to you. Use the API or MCP Server when you need to read or write data on demand.

---

Questions?

If a webhook is not arriving, note your organization, endpoint URL (redact secrets), the event you expected, and the HTTP status your server returned, then contact us via Open a ticket at the bottom of this page.