Webhooks

Overview Pro - Requires the Pro plan

Webhooks let you receive automatic POST notifications on your own server when something happens in your schedules: a ticket is sold or refunded, an event changes, a ticket is scanned at the door. Instead of polling the API, your application is notified as it happens.

Each delivery carries an HMAC-SHA256 signature so you can verify the payload really came from Event Schedule, and every delivery is written to a delivery log you can open from your settings.

Webhooks belong to your account, not to an individual schedule, and each delivery goes to the account that created the event. Events you create, in the admin panel or through the API, reach your endpoints whichever schedule they sit on, along with every sale on them. An event a teammate created goes to their webhooks instead of yours, and a guest's submission counts as the schedule owner's. The schedule is identifiable from the payload. Add more than one endpoint if you want to route different event types to different services.

How a delivery works

Setup

1. Open Settings in the admin panel and choose Webhooks, then scroll to the Add Webhook form.
2. Enter the Webhook URL. It has to be a publicly reachable address, so localhost and private network addresses are refused with "This URL is not allowed." Use HTTPS: the payload contains buyer names, email addresses and ticket links.
3. Optionally add a Description, a label for your own reference that appears above the URL in the list.
4. Under Event types, switch off anything you do not want. Every type is on by default, and leaving them all on subscribes the endpoint to everything, including any type added later. Switching every type off saves the same thing, a subscription to everything, so use Disable to silence a webhook instead.
5. Click Add Webhook. The signing secret, a 64-character hex string, is shown once with a copy button. Store it before you leave the page: it cannot be displayed again.
6. Send a test ping with the Test button on the saved webhook and confirm your endpoint answers with a 2xx status. The result is reported as "Test webhook sent successfully (HTTP 200)." or, with the status it did get, "Test webhook failed (HTTP 500)."

Managing a webhook

Each saved webhook shows its description, URL, the event types it subscribes to (or an All events badge) and when it was last triggered. The icon buttons on the right of the row do the following.

• Enable / Disable - the check-circle icon, a crossed-out circle while the webhook is off, pauses or resumes it. A disabled webhook is dimmed in the list and receives nothing, but keeps its secret and its delivery history.
• Test - the lightning icon sends the test payload described under Testing.
• Edit - the pencil icon opens an inline form for the URL, description and event types. Regenerate secret sits at the bottom of that form; it issues a new secret, shows it once, and immediately invalidates the old one, so update your endpoint in the same sitting.
• Delete - the trash icon removes the webhook and its delivery log after a confirmation.
• View recent deliveries - the link under the row expands the last 20 attempts with the event type, response status, duration and time.

Event Types

These are the fourteen event types you can subscribe to. They are the same list, in the same order, as the switches on the Add Webhook form.

Payload Format

Every payload uses the same three-key envelope: the type in event, an ISO 8601 timestamp, and the record itself in data. Abbreviated example of a sale.paid delivery:

{
"event": "sale.paid",
"timestamp": "2026-03-01T12:00:00+00:00",
"data": {
"id": "abc123",
"event_id": "def456",
"event_name": "Summer Concert",
"name": "Jane Doe",
"email": "[email protected]",
"status": "paid",
"payment_amount": 25.00,
"tickets": [
{ "ticket_id": "ghi789", "quantity": 2, "price": 12.50, "type": "General" }
]
}
}

For sale.* and event.* the data object is the same record the Sales API and Events API return, so one parser can handle both. The real object carries more than the sample above: a sale also includes subdomain, phone, event_date, payment_method, transaction_reference, discount and gift-card totals, total_quantity, group_id, is_primary and timestamps, and each ticket row carries is_addon, is_pass, for a pass its usage counters, and on an event with allocated seating the seats it holds. There is no currency field: read the event's ticket_currency_code from the Events API.

Types with extra fields

• installment.paid and installment.failed add an installment object with sequence, amount, outcome, reference and a plan summary: status, currency, total_amount, amount_paid, amount_remaining, installment_count, installments_paid, next_due_at and next_amount.
• ticket.scanned from a pass adds scanned_event_id and scanned_event_date, so you can tell which occurrence the pass was used on.
• ticket.booked adds booked_event_id and booked_event_date.
• ticket.booking_cancelled adds the same two fields plus forfeited, which is true when the release happened after the cancellation cutoff and the visit was used up.
• feedback.submitted is the one type that does not follow the API shape. Its data holds event_id, event_name, event_date, attendee_name, attendee_email, rating and comment, and it has no id.

Request Headers

Signature Verification

Every webhook includes an X-Webhook-Signature header containing an HMAC-SHA256 hash of the raw request body, signed with your webhook secret. Always verify this signature before processing the payload.

The signature covers the request body exactly as sent and nothing else, so hash the raw bytes before any JSON parsing or re-encoding. Compare with a constant-time function, never with ==.

PHP

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $webhookSecret);

if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}

$data = json_decode($payload, true);

Node.js

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
const expected = Buffer.from('sha256=' +
crypto.createHmac('sha256', secret).update(body).digest('hex'));
const received = Buffer.from(signature || '');
// timingSafeEqual throws when the lengths differ
return expected.length === received.length &&
crypto.timingSafeEqual(expected, received);
}

Python

import hmac, hashlib

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

Best Practices

• Respond quickly. Return a 2xx status within 5 seconds. Queue the real work and acknowledge receipt first: a slower reply is recorded as a timeout and retried, so work that finished after the deadline can reach you twice.
• Verify signatures. Always validate the X-Webhook-Signature header before processing any payload, and reject anything that does not match.
• Treat each delivery as the latest state. One record can be reported many times in ordinary use: event.updated fires on every save of a published event, and a retry repeats the same body when your endpoint handled it but answered late or with a 5xx. Key on data.id together with event, and fall back to the event and attendee for feedback.submitted, which has no id.
• Answer at the registered URL. Redirects are not followed, so a 301 from http to https or from a bare domain to www is recorded as a failure, and a 3xx is not retried. Register the final URL.
• Use HTTPS. Payloads carry buyer names, email addresses and ticket secrets, so they should never cross the network in the clear.
• Reconcile what you cannot miss. Retries cover a blip of a minute or two, not an outage: after the third attempt, or after a 3xx or 4xx, a delivery is not tried again, and an install on the sync queue makes only the one attempt. After an outage on your side, catch up from the Sales API, for example with GET /api/sales?status=refunded.
• Monitor deliveries. Open View recent deliveries in your webhook settings to debug failures. The first 500 characters of the response body you return are stored with the log, so a descriptive error message there pays for itself.

Testing

Use the Test button in your webhook settings to send a test payload. The test event uses the type webhook.test with an empty data object:

{
"event": "webhook.test",
"timestamp": "2026-03-01T12:00:00+00:00",
"data": {}
}

The test is signed and sent exactly like a real delivery, with the same headers and the same 5 second timeout, so it verifies your signature check as well as your URL. It ignores the event types you subscribed to, it is sent even to a disabled webhook, and it works whatever plan your schedules are on, which makes it the quickest way to prove the endpoint itself before you wait for real activity. It is sent once, so a failed test is not retried, and the result is written to the delivery log alongside everything else.

See Also

• REST API Reference - The same records over HTTP, for anything you need to pull rather than be pushed
• Account Settings - Where webhooks, API keys and connected services are configured
• Selling Tickets - The ticketing and check-in features behind the sale and scan events