Webhook reference

This page is for developers writing their own receiver. Sortr sends each ticket event as an HTTPS POST with a JSON body, signed with the webhook's secret. Setting a webhook up in the dashboard is covered in Webhooks.

#The request

One request per event per webhook. Header names are case-insensitive.

POST /your/path HTTP/1.1
Content-Type: application/json
User-Agent: Sortr-Webhooks/1.0 (+https://sortr.xyz)
Sortr-Event: ticket.opened
Sortr-Event-Id: evt_3f9a1c07d2e84b6c5a0e7d21
Sortr-Signature: t=1790517731,v1=5257a869e7ecebeda32a…

The body is compact JSON on one line. The examples below are spread out to be readable.

#Fields in every event

Ticket events add a ticket object and fields of their own.

A ticket Sortr took over from Ticket Tool sends events from the take-over on, to the webhooks of the panel it runs on (none when it runs on Sortr's defaults). There is no ticket.opened for it. Its opened_at is when Ticket Tool made the channel, and its number is the one in its channel name where Sortr had not used it.

#The ticket object

#The user object

username and display_name are null when Sortr could not look the member up, for example after they left the server. The owner of a ticket.deleted event with deleted_in_discord: true always has them as null.

#ticket.opened

#Answers with files

An answer to a question that takes files (Answer set to Files on the panel's Questions screen) is { "question", "answer", "files" }. Text answers never have files.

There is no link to the file. Discord's own links expire, so Sortr posts a copy of the files in the ticket channel instead, and stores only their names. Every attached file is listed here, including one Sortr did not copy into the ticket, for example because it was too big or of a kind the question does not take.

{
  "id": "evt_3f9a1c07d2e84b6c5a0e7d21",
  "type": "ticket.opened",
  "created_at": "2026-09-27T14:02:11.412Z",
  "server": { "id": "100000000000000000", "name": "Aurora SMP" },
  "panel": { "id": "100000000000000000-mfk2q8x1a7c", "name": "Billing" },
  "ticket": {
    "id": 1842,
    "number": "0042",
    "channel_id": "100000000000000003",
    "owner": { "id": "100000000000000001", "username": "ren.oakley", "display_name": "Ren" },
    "opened_at": "2026-09-27T14:02:11.000Z",
    "closed_at": null
  },
  "opened_by": { "id": "100000000000000001", "username": "ren.oakley", "display_name": "Ren" },
  "answers": [
    { "question": "What do you need help with?", "answer": "My order never arrived." },
    { "question": "Order number", "answer": "#10442" },
    {
      "question": "Screenshots",
      "answer": "receipt.png",
      "files": [{ "name": "receipt.png", "size": 188416, "content_type": "image/png" }]
    }
  ]
}

#ticket.closed

transcript_url is always null for a panel that saves transcripts when the ticket is deleted (Save it set to When the ticket is deleted under Transcripts/Logging), since nothing is saved at the close. It is also null when the panel keeps no transcripts, when it only sends them to the ticket owner by direct message, or when the save at the close made no copy. For a ticket taken over from Ticket Tool whose transcript was kept off a channel others can read, it is the sortr.xyz page, even when the panel keeps no copy there (Transcripts).

A sortr.xyz transcript link opens only for the member who opened the ticket and for the server's owner and Administrators, after they sign in with Discord. In a server that requires 2FA for moderator actions, an Administrator also needs 2FA on their Discord account. Anyone else sees the same "No such transcript" page as for a link that does not exist. The link stops working once that copy is deleted: when the panel's Keep it for runs out, when newer saves push it out of the copies the ticket keeps (its first and its 3 newest), when an admin deletes it, or 30 days after Sortr is removed from the server.

{
  "id": "evt_a41c7e02b95d3f80c6e1d7b2",
  "type": "ticket.closed",
  "created_at": "2026-09-27T14:17:48.530Z",
  "server": { "id": "100000000000000000", "name": "Aurora SMP" },
  "panel": { "id": "100000000000000000-mfk2q8x1a7c", "name": "Billing" },
  "ticket": {
    "id": 1842,
    "number": "0042",
    "channel_id": "100000000000000003",
    "owner": { "id": "100000000000000001", "username": "ren.oakley", "display_name": "Ren" },
    "opened_at": "2026-09-27T14:02:11.000Z",
    "closed_at": "2026-09-27T14:17:48.000Z"
  },
  "closed_by": { "id": "100000000000000002", "username": "mira.k", "display_name": "Mira" },
  "automatic": false,
  "reason": "Refund issued",
  "transcript_url": "https://sortr.xyz/t/9c2e41d0-7b3a-4f6e-9d8c-2a1b3c4d5e6f"
}

#ticket.reopened

{
  "id": "evt_0d6b93e5f2a7c14e8b90a3d6",
  "type": "ticket.reopened",
  "created_at": "2026-09-27T15:40:02.118Z",
  "server": { "id": "100000000000000000", "name": "Aurora SMP" },
  "panel": { "id": "100000000000000000-mfk2q8x1a7c", "name": "Billing" },
  "ticket": {
    "id": 1842,
    "number": "0042",
    "channel_id": "100000000000000003",
    "owner": { "id": "100000000000000001", "username": "ren.oakley", "display_name": "Ren" },
    "opened_at": "2026-09-27T14:02:11.000Z",
    "closed_at": null
  },
  "reopened_by": { "id": "100000000000000002", "username": "mira.k", "display_name": "Mira" }
}

#ticket.deleted

A delete through Sortr is sent before the channel goes. When the delete saves a transcript first, the event is sent after that save and after the last notice in the channel. The channel itself is removed a few seconds later: 8 seconds after a delete by hand, 10 after the automatic delete. With deleted_in_discord: true, the channel was already gone when the event was made.

A delete saves a transcript first when the panel saves transcripts when the ticket is deleted (Save it set to When the ticket is deleted), or when the ticket has no copy since its last close, such as a ticket deleted while still open. Otherwise the ticket already has a copy, saved at the close (the one in ticket.closed) or by hand since, and transcript_url here is null. It is also null when the panel keeps no transcripts, when the save made no copy or only sent one by direct message, and always with deleted_in_discord: true, since a channel deleted in Discord cannot be saved. ticket.closed_at is null for a ticket deleted while it was still open.

{
  "id": "evt_e87f20a9c3b64d15f0a2c9e4",
  "type": "ticket.deleted",
  "created_at": "2026-10-04T14:20:31.907Z",
  "server": { "id": "100000000000000000", "name": "Aurora SMP" },
  "panel": { "id": "100000000000000000-mfk2q8x1a7c", "name": "Billing" },
  "ticket": {
    "id": 1842,
    "number": "0042",
    "channel_id": "100000000000000003",
    "owner": { "id": "100000000000000001", "username": "ren.oakley", "display_name": "Ren" },
    "opened_at": "2026-09-27T14:02:11.000Z",
    "closed_at": "2026-09-27T16:05:19.000Z"
  },
  "deleted_by": null,
  "automatic": true,
  "deleted_in_discord": false,
  "transcript_url": null
}

#ping (the test event)

Send test in the dashboard posts a ping to the address and secret in the editor, saved or not. It has the fields every event has, plus a message, and no ticket. It is sent once, never retried, and not listed under Recent deliveries. Answer it with any 2xx.

{
  "id": "evt_7b2e90c4a1d35f68e0c9b417",
  "type": "ping",
  "created_at": "2026-09-27T14:00:00.000Z",
  "server": { "id": "100000000000000000", "name": "Aurora SMP" },
  "panel": { "id": "100000000000000000-mfk2q8x1a7c", "name": "Billing" },
  "message": "A test from Sortr. If you can read this, Sortr can reach this address."
}

#Verify the signature

Sortr-Signature looks like t=1790517600,v1=820da578….

• t is the time of this delivery attempt in whole seconds since 1970 (UTC). A retry carries a new t and a new signature.
• v1 is the HMAC-SHA256, in lowercase hex, of t, a full stop and the raw request body: "<t>.<body>". The key is the webhook's whole signing secret, whsec_ prefix included.

The dashboard makes the secret when you press New secret: whsec_ followed by 32 random letters, digits, - and _. Sortr only signs with a secret of that shape, 32 to 64 such characters after whsec_, at least 16 of them different. One that falls short is never used, and saving the panel asks for a new one.

1. Read the raw body. Take the bytes exactly as they arrived, before any JSON parsing. Re-serialised JSON will not match.
2. Compute the signature. HMAC-SHA256 of t, . and the body, keyed with the secret.
3. Compare. Compare it with v1 using a constant-time comparison.
4. Check the time. We recommend rejecting a t more than 5 minutes from your clock, so an old request replayed later fails.

#Node.js

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const SECRET = process.env.SORTR_WEBHOOK_SECRET; // the whole secret, whsec_ included
const TOLERANCE_SECONDS = 5 * 60;

// rawBody is a Buffer: the request body exactly as it arrived
function fromSortr(rawBody, header, secret) {
  const parts = {};
  for (const piece of (header ?? "").split(",")) {
    const [key, value] = piece.trim().split("=");
    if (key && value) parts[key] = value;
  }
  if (!/^\d+$/.test(parts.t ?? "") || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > TOLERANCE_SECONDS) return false;

  const expected = createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest("hex");
  const given = Buffer.from(parts.v1);
  return given.length === expected.length && timingSafeEqual(given, Buffer.from(expected));
}

const app = express();

app.post("/sortr", express.raw({ type: "application/json" }), (req, res) => {
  if (!fromSortr(req.body, req.get("Sortr-Signature"), SECRET)) return res.sendStatus(400);
  const event = JSON.parse(req.body.toString("utf8"));
  // Answer first, then do the slow work.
  res.sendStatus(204);
  handle(event); // your own code
});

#Python

import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

SECRET = os.environ["SORTR_WEBHOOK_SECRET"]  # the whole secret, whsec_ included
TOLERANCE_SECONDS = 5 * 60


def from_sortr(raw_body, header, secret):
    parts = {}
    for piece in (header or "").split(","):
        key, _, value = piece.strip().partition("=")
        if key and value:
            parts[key] = value
    t, v1 = parts.get("t", ""), parts.get("v1")
    if not t.isdigit() or not v1:
        return False
    if abs(time.time() - int(t)) > TOLERANCE_SECONDS:
        return False
    signed = t.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)


app = Flask(__name__)


@app.post("/sortr")
def sortr():
    raw = request.get_data()  # the body exactly as it arrived
    if not from_sortr(raw, request.headers.get("Sortr-Signature"), SECRET):
        abort(400)
    event = request.get_json()
    # queue the event for your own processing here, then answer
    return "", 204

#Check your code against this

With the secret whsec_Zx4kQ9mT2vLr8NpB6yHc3WdF7gJs1aEu (an example, not a real one), t=1790517600 and this exact body:

{"id":"evt_7b2e90c4a1d35f68e0c9b417","type":"ping","created_at":"2026-09-27T14:00:00.000Z","server":{"id":"100000000000000000","name":"Aurora SMP"},"panel":{"id":"100000000000000000-mfk2q8x1a7c","name":"Billing"},"message":"A test from Sortr. If you can read this, Sortr can reach this address."}

the signature is:

Sortr-Signature: t=1790517600,v1=820da5780524d86db543367d9679e48749f5e16c4ec375aecb068dee75b27406

Leave out the time check while testing with this, since t is in the past.

#Responding

• Answer with any 2xx status within 10 seconds. The body of your answer is ignored.
• Anything else counts as a failure and is retried: another status, no answer in time, a refused connection or an invalid TLS certificate.
• Redirects are not followed. A 3xx is a failure, and the dashboard asks the admin to paste the final address.
• Answer before doing slow work. Store or queue the event, respond, then process it. A 2xx that takes longer than 5 seconds still counts as delivered, but your webhook's next events then wait 30 seconds before Sortr sends them.

#Retries

A failed delivery is tried again after a wait that doubles each time, measured from the failed attempt:

Sortr looks for due retries every 15 seconds, so an attempt can come a little later than listed. When an attempt fails and the event is more than a day old, Sortr gives up. An address that can never work as it is, such as one that resolves to a private network, is given up on at once without retries.

#How delivery works

• At least once. The same event can arrive more than once, for example when your code handled it but its answer did not reach Sortr within 10 seconds. Use id (or Sortr-Event-Id) to spot repeats. Every webhook on the panel receives the same id for the same event.
• Order. Each webhook receives its events one at a time, in the order they happened. While one is being retried, every later event for that webhook waits behind it, including events that happen during the wait, so a ticket.closed never arrives before the ticket.opened it follows. An event Sortr gives up on is skipped, and the next one goes out. Different webhooks are independent of each other.
• Settings at send time. Waiting events go to the webhook's current address, signed with its current secret. If the webhook is switched off, removed, or no longer wants that event, its waiting events are not sent, and the dashboard lists them as Not sent.
• Backlog. At most 500 events wait for one webhook. While 500 are waiting, each newer event is not sent: the dashboard lists it as Failed with "Not sent: 500 earlier events are still waiting for this address." New events are queued as usual again once fewer than 500 are waiting. A server has a cap of its own, 2,000 events waiting across all its webhooks, with "Not sent: this server already has 2,000 events waiting to be sent."
• Slow answers. A 2xx that takes longer than 5 seconds is a delivery, not a failure. That webhook's next events wait 30 seconds, still in order, and the wait does not count as a failed try.

#Address rules

• https:// only, with a valid certificate, on port 443 or a port above 1023.
• Public addresses only. The name is looked up on every attempt, and if any address it resolves to is private, loopback, link-local or otherwise reserved, or is one of the addresses of Sortr's own server (those sortr.xyz resolves to), the request is not made: "That address is on a private network. Sortr only sends to public addresses."
• No user name or password in the address, at most 500 characters, and not on a Discord host (discord.com, discordapp.com, discordapp.net, discord.gg, discord.media or any subdomain of them), whatever the path. Such an address is refused on save and on Send test, and gets no events: "Discord can't take Sortr's events. To post them in a channel, use the Event log under Transcripts/Logging."
• Two switched-on webhooks on one panel can't share an address. A panel has at most 5 webhooks.