Webhooks
Receive signed HTTP notifications for 23 ticket events and connect TicketCord to Zapier, Make, Slack, or your own service
Webhooks send an HTTP POST to a URL you choose every time something happens in your tickets: a ticket is created or closed, a message arrives, a priority changes, an SLA is breached, an approval is decided, and so on.
Each request is signed so your receiver can prove it came from TicketCord. Use them to push tickets into a CRM, alert a Slack channel, or drive automation platforms such as Zapier, Make, or n8n. They are for Enterprise servers that need TicketCord data outside Discord and the dashboard.
Webhooks are an Enterprise feature. Each server can have up to 20 webhooks, and each webhook delivers at most 60 events per minute. Only the bot owner can create, edit, test, or delete webhooks and view delivery logs; dashboard staff see the list with the URL hidden. Upgrade your plan to use webhooks.
Creating a webhook
Open Webhooks
Go to General → Webhooks. The count next to the card's title shows how many of your 20 webhooks are in use, for example 2/20.
Click Add webhook
The Add a webhook dialog opens. Enter a Name (only you see it) and the Webhook URL your receiver gave you, then tick the events you want under Events to send.
Each event says in plain words what happens, with its event name under it, for example A ticket is opened (ticket.created). Events are grouped as Ticket lifecycle, Messages, Priority & SLA, Sentiment & approvals, and Notes & access control, and Select all ticks a whole group.
Pick at least one, then click Add webhook.
Save the secret
On Webhook added, click Copy next to Webhook secret (or Show to read it) and store it somewhere safe. It is shown once and cannot be retrieved later. You need it to verify signatures; most no-code platforms do not.
Send a test
Open the ⋯ menu on the webhook's row and choose Send a test. The row shows Sending a test…, then Test sent once a test payload is queued for delivery under the first event type you subscribed to. The result appears in Delivery history within a minute.
For no-code platforms (Zapier, Make, n8n), paste the catch-hook URL the platform gives you as the Webhook URL, subscribe to the events you need, and map the fields from the payloads below. Signature verification is optional there.
Settings
| Field | Allowed values | Default |
|---|---|---|
| Name | 1 to 50 characters: letters, numbers, spaces, hyphens, underscores | required |
| Webhook URL | https:// only, public hostname, no embedded credentials | required |
| Events to send | any of the 23 events below, at least one | none |
| Active | on or off (the switch on the row) | on |
| Retry policy (advanced, not in the form) | up to 5 retries, backoff multiplier 1 to 5, initial delay 100 ms to 10 s | 3 retries, multiplier 2, 1 s |
URL rules are enforced on save and again at delivery time: http://, localhost, private and internal IP addresses, and hostnames that resolve to them are rejected with messages such as "Webhook URL must use HTTPS protocol" or "Webhook hostname resolves to an internal/private IP address".
Events
TicketCord sends 23 event types.
| Group | Events |
|---|---|
| Ticket lifecycle | ticket.created, ticket.claimed, ticket.unclaimed, ticket.closed, ticket.reopened, ticket.deleted, ticket.renamed |
| Messages | message.created, message.edited, message.deleted |
| Priority and SLA | priority.changed, sla.warning, sla.breach |
| Sentiment and approvals | sentiment.negative, approval.requested, approval.approved, approval.denied |
| Notes and access | ticket.note.added, ticket.note.removed, ticket.user.added, ticket.user.removed, ticket.role.added, ticket.role.removed |
sla.* events need SLA Management, approval.* events need Approval Workflows, and sentiment.negative needs Sentiment Detection to be enabled on the server; otherwise they never fire.
Request format
Every delivery is a POST with a JSON body and these headers:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | TicketCord-Webhooks/1.0 |
X-TicketCord-Event | The event type, for example ticket.created |
X-TicketCord-Event-Id | The event's ID, the same on every retry |
X-TicketCord-Timestamp | Unix time in seconds when the request was signed |
X-TicketCord-Signature | Hex HMAC-SHA256 signature (see below) |
The body always has the same envelope:
{
"eventId": "6f1c2f1e-7a3b-4a52-9c1d-2b3e4f5a6b7c",
"event": "ticket.created",
"timestamp": 1702483200,
"data": { },
"attemptNumber": 1
}| Field | Type | Meaning |
|---|---|---|
eventId | string | The event's ID, identical to the header and the same on every retry |
event | string | Event type, identical to the header |
timestamp | number | Unix time in seconds, identical to the header |
data | object | Event payload; shape depends on the event |
attemptNumber | number | 1 for the first try, 2 and up for retries |
Redirects are not followed, so the URL must answer directly. Any 2xx status counts as success; the response body is ignored.
Payloads
Fields marked optional are omitted when empty. IDs are strings; times are ISO 8601.
ticket.created, ticket.claimed, ticket.closed, ticket.reopened, ticket.deleted
ticketId, ticketNumber, channelId, creatorId, ticketType, and optionally creatorName, claimerId, claimerName, category, priority, subject, createdAt, closedAt, reopenedAt, deletedAt, closeReason, reopenReason, staffMemberId, staffName.
ticket.deleted is also sent when TicketCord finishes an auto-close's channel delete that a restart interrupted.
ticketType says where the ticket lives: channel (its own text channel), thread (a thread, when threaded tickets are on) or modmail (a ModMail ticket). For a thread ticket, channelId is the thread's ID and category is the ID of the text channel the thread was opened in, not a Discord category. For a channel or ModMail ticket, category is the ID of the ticket's Discord category.
{
"event": "ticket.closed",
"timestamp": 1702486800,
"data": {
"ticketId": "507f1f77bcf86cd799439011",
"ticketNumber": 42,
"channelId": "111222333444555666",
"creatorId": "123456789012345678",
"ticketType": "channel",
"creatorName": "John Doe",
"closedAt": "2024-12-13T11:00:00.000Z",
"closeReason": "Issue resolved",
"staffMemberId": "999888777666555444",
"staffName": "Support Agent"
},
"attemptNumber": 1
}ticket.unclaimed
ticketId, ticketNumber, channelId, previousClaimer, unclaimedBy, unclaimedAt, optionally previousClaimerName, unclaimedByName.
When Auto-unclaim released the claim, unclaimedBy is SYSTEM_AUTO_UNCLAIM instead of a user ID, unclaimedByName is Auto-unclaim, and two more fields are sent: automatic (true) and reason (no_reply when the member waited too long for a staff reply, member_quiet when the member stopped answering).
ticket.renamed
ticketId, ticketNumber, channelId, oldName, newName, renamedBy, renamedAt, optionally renamedByName.
message.created, message.edited, message.deleted
messageId, ticketId, channelId, authorId, content, embeds (count), attachments (count), isStaff, isBot, createdAt, optionally authorName, editedAt, deletedAt, oldContent, deletedBy, mentions (array of user IDs), roleMentions (array of role IDs).
{
"event": "message.created",
"timestamp": 1702484500,
"data": {
"messageId": "222333444555666777",
"ticketId": "507f1f77bcf86cd799439011",
"channelId": "111222333444555666",
"authorId": "123456789012345678",
"authorName": "John Doe",
"content": "Hello, I need help with my subscription.",
"embeds": 0,
"attachments": 1,
"isStaff": false,
"isBot": false,
"createdAt": "2024-12-13T10:15:00.000Z"
},
"attemptNumber": 1
}priority.changed
ticketId, channelId, oldPriority, newPriority, changedBy, changedByName, timestamp, optionally reason.
sla.warning, sla.breach
ticketId, channelId, priority, eventType (warning or breach), slaType (first_response or resolution), targetMinutes, elapsedMinutes, percentageUsed, timestamp, optionally remainingMinutes, breachTime, warningPercentage, assignedStaff, assignedStaffName, escalationLevel, idempotencyKey.
sentiment.negative
Sent when Atlas finds a member angry, frustrated, or upset with enough confidence to alert, whether or not a tone alert is posted in Discord.
ticketId, channelId, messageId (the member's newest message in the ticket channel; empty when the ticket only has its form answers), customerId, sentiment (angry, frustrated, or upset), confidence (0 to 1), timestamp, optionally customerName, messageContent (first 200 characters), detectedTone, assignedStaff.
approval.requested, approval.approved, approval.denied
approvalId, ticketId, channelId, approvalType (refund, ban, policy_exception, escalation, custom), eventType (requested, approved, rejected), requestedBy, requestedAt, optionally requestedByName, approverId, approverName, reason, decision (approved or rejected), decisionReason, decidedAt, customerId, amount, metadata.
ticket.note.added, ticket.note.removed
noteId, ticketId, ticketNumber, channelId, authorId, optionally authorName, content (added only), createdAt, removedBy, removedByName, removedAt.
ticket.user.added, ticket.user.removed, ticket.role.added, ticket.role.removed
ticketId, ticketNumber, channelId, eventType (user_added, user_removed, role_added, role_removed), targetType (user or role), targetId, performedBy, performedAt, optionally targetName, performedByName.
Test payload (Send a test)
Sent under your first subscribed event type: test: true, message: "This is a test webhook delivery from TicketCord", timestamp (ISO), botId, guildId, webhookId.
Verifying signatures
Every request is signed with your webhook secret, a 64-character hex string shown once at creation.
- Read
X-TicketCord-Timestamp(Unix seconds) andX-TicketCord-Signature. - Take the raw request body exactly as received, before any JSON parsing.
- Build the string
v0:<timestamp>:<raw body>. - Compute HMAC-SHA256 of that string with your secret and encode it as lowercase hex.
- Compare it to the header with a constant-time comparison. There is no
v0=prefix on the header value; it is the bare hex digest. - Reject requests whose timestamp is more than 5 minutes old to block replays.
Node receiver with verification
const express = require('express');
const crypto = require('crypto');
const app = express();
const SECRET = process.env.TICKETCORD_WEBHOOK_SECRET;
// Keep the raw body: the signature covers the exact bytes TicketCord sent.
app.use('/webhooks/ticketcord', express.raw({ type: 'application/json' }));
function verify(rawBody, timestamp, signature) {
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const expected = crypto
.createHmac('sha256', SECRET)
.update(`v0:${timestamp}:${rawBody.toString('utf8')}`)
.digest('hex');
const a = Buffer.from(expected, 'hex');
const b = Buffer.from(signature, 'hex');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/webhooks/ticketcord', (req, res) => {
const signature = req.get('X-TicketCord-Signature') || '';
const timestamp = req.get('X-TicketCord-Timestamp') || '';
if (!verify(req.body, timestamp, signature)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const { eventId, event, data, attemptNumber } = JSON.parse(req.body.toString('utf8'));
// Acknowledge first, then do the real work so you stay under the 30 s timeout.
res.status(200).json({ received: true });
setImmediate(() => {
if (attemptNumber > 1) {
// A retry: skip it if you already handled this eventId.
}
switch (event) {
case 'ticket.created':
console.log(`New ticket #${data.ticketNumber} from ${data.creatorName}`);
break;
case 'sla.breach':
console.log(`SLA ${data.slaType} breached on ${data.ticketId}`);
break;
default:
console.log(`Received ${event}`);
}
});
});
app.listen(3000);Python receiver with verification
import os, hmac, hashlib, time
from flask import Flask, request, jsonify, abort
app = Flask(__name__)
SECRET = os.environ['TICKETCORD_WEBHOOK_SECRET'].encode()
def verify(raw: bytes, timestamp: str, signature: str) -> bool:
try:
age = abs(int(time.time()) - int(timestamp))
except ValueError:
return False
if age > 300:
return False
expected = hmac.new(SECRET, f"v0:{timestamp}:".encode() + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
@app.post('/webhooks/ticketcord')
def receive():
if not verify(request.get_data(), request.headers.get('X-TicketCord-Timestamp', ''),
request.headers.get('X-TicketCord-Signature', '')):
abort(401)
payload = request.get_json()
print(payload['event'], payload['data'].get('ticketId'))
return jsonify(received=True), 200Respond with 200 as soon as the signature checks out and process the event afterwards. A receiver that takes longer than 30 seconds is treated as failed and retried, which means duplicate work for you.
Delivery, retries, and rate limits
- Timeout: 30 seconds per request.
- Success: any
2xxresponse. - Retries: a failed delivery (non-
2xx, timeout, or connection error) is retried up to 3 times by default with exponential backoff of 1 s, 2 s, then 4 s (capped at 5 minutes for custom policies). After a timeout, deliveries to that webhook also pause for 30 seconds, so a retry can come later than the backoff.attemptNumberin the body tells you which try you are seeing. - 429 responses: not counted as a failure. Delivery pauses for the seconds given in your
Retry-Afterheader (60 if absent, at most 300) and is queued again. An event that has waited 24 hours for your endpoint to recover is logged as failed and not sent again. - Rate limit: 60 deliveries per minute per webhook. Events beyond that are held and delivered later, not dropped.
- Duplicates: an event you already accepted is not sent again. You can still see one twice in rare cases, such as a retry after your server handled the request but answered too slowly. Keep track of
eventIdand ignore one you have already handled. - Ordering: events are delivered as they are queued, but retries and rate limiting can reorder them. Use the timestamps in
datarather than arrival order. - Counters: each webhook row shows how many events it subscribes to, how many deliveries worked and failed (for example "12 delivered, 1 failed"), and when it last sent one ("Last sent" with a date, or Nothing sent yet). After the first delivery, a pill next to the name says whether the last one worked: Working or Failing.
Delivery logs
Delivery history in a webhook row's ⋯ menu lists the deliveries of the last 30 days, newest first, with columns Sent, Event, Result, Took, and Error (on a phone each delivery is a stacked row).
Result is Delivered or Failed with the HTTP status code, and a retry also shows which try it was, for example Try 2.
You can narrow the list:
- Filter by event.
- Filter by result (Delivered, Failed, or one HTTP status code).
- Filter by time window (Last hour, Last 24 hours, Last 7 days, Last 30 days).
- Search events and error text.
Clear filters resets them. The history is read-only; there is no button to resend a specific delivery, so use Send a test or trigger the event again.
Limits and gotchas
- The secret is shown only once. There is no way to reveal or rotate it later; to get a new secret, delete the webhook and create it again.
- 20 webhooks per server. At the limit, Add webhook is greyed out, the card says the server has reached its limit, and saving a new webhook past the limit fails with "Webhook limit reached".
https://only, no redirects, and no private or internal addresses. Tunnels such as ngrok work for testing because they expose a public HTTPS hostname.- The webhook URL and the delivery logs are visible to the bot owner only. Dashboard staff see each webhook's name, counters, and health, with an Owner only badge.
- Editing the event list takes effect for new events immediately.
- Turning the row's switch off stops deliveries without losing the configuration or the secret.
- Deleting a webhook deletes its delivery history too; the confirmation says the webhook "stops receiving events and its delivery history is deleted."
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| "Webhook URL must use HTTPS protocol" | The URL starts with http:// | Use an HTTPS endpoint |
| "Internal/private IP addresses are not allowed" or "...resolves to an internal/private IP address" | The host is on a private network or loopback | Expose the receiver on a public hostname, or use a tunnel |
| "Webhook name can only contain letters, numbers, spaces, hyphens, and underscores" | Disallowed characters in Name | Rename it |
| "Webhook limit reached" | 20 webhooks already exist | Delete an unused one |
Log shows HTTP 401 or 403 from your server | Your receiver rejected the signature or requires auth headers TicketCord does not send | Check the verification code against the six steps above; make sure you hash the raw body |
| Log shows "Request timeout (30s)" | Your receiver did not answer within 30 seconds | Return 200 immediately and process afterwards |
| Delivery history shows "DNS lookup failed" or "Connection refused" | The hostname or port is wrong, or the server is down | Fix the URL and test with Send a test |
| Log shows "SSL certificate error" | The certificate is self-signed, expired, or for another hostname | Use a valid certificate |
| Events arrive twice | A retry after a slow or failed response | Respond faster and ignore an eventId you have already handled |
| Events arrive late or in bursts | The 60 per minute rate limit or a 429 pause | Raise your endpoint's own limit or spread work across two webhooks with different event sets |
No sla.*, approval.*, or sentiment.negative events | The feature that produces them is not enabled on the server | Turn on Staff → Response targets, Staff → Approvals, or AI assistant → Atlas → Alert staff to upset members |
| Signature check fails only for some events | The body was parsed and re-serialised before hashing | Hash the raw bytes exactly as received |
| The webhook's URL reads "Visible to the bot owner only" | You are dashboard staff | Ask the bot owner |
Common questions
Where do I set up webhooks? In General → Webhooks. They are per server, not per bot or account.
I lost my webhook secret. Can I see it again? No. It is shown once at creation. Delete the webhook and create a new one to get a new secret.
Do I have to verify signatures? For your own receiver, yes; otherwise anyone who learns the URL can send you fake events. For Zapier, Make, or n8n catch hooks it is optional.
How is the signature computed?
HMAC-SHA256 over the string v0:<timestamp>:<raw body> using your secret, sent as lowercase hex in X-TicketCord-Signature. The timestamp is Unix seconds from X-TicketCord-Timestamp.
How many times will a failed delivery be retried?
Three times by default, after 1, 2, and 4 seconds, plus a 30-second pause after a timeout. A 429 with Retry-After pauses delivery instead of using a retry, for up to 24 hours. After the last failed attempt the delivery is logged as failed and not sent again.
Can I get a Discord message instead of an HTTP request? Not through this feature. Webhooks post JSON to a URL. To announce tickets in a Discord channel, point a Zapier, Make, or n8n scenario at a Discord channel webhook.
Can I send webhooks to more than one server? Each server has its own webhooks and its own limit of 20. Set them up on each server separately.
Which plan do I need? Enterprise. On lower plans the Webhooks card shows only an Enterprise badge (a link to Plan & billing) and no webhooks can be created.
Join our Discord server for support
Was this page helpful?
Last updated on
Data Export Reference
Every section of a TicketCord GDPR data export, the file format, what account deletion removes and keeps, and the retention rules behind both
Game Accounts
Show each member's Roblox, Steam and FiveM or RedM account on their tickets, use them in messages, and require them before a ticket opens