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 beside the webhook. Webhooks are added and managed in the admin panel, under Settings, on the Developers tab.

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

Webhooks are set up in the admin panel: open Settings, choose the Developers tab, and find Webhooks under API Settings. If none of your schedules is on Pro, the section says so at the top.

Open full size

Open full size

1. With no webhook yet, the Add Webhook form is already open. Once you have one, open it with + Add Webhook under the list.
2. Enter the Webhook URL, up to 2,048 characters. It has to be a publicly reachable address: localhost, a private network address and a host name that does not resolve are all refused with "This URL is not allowed." under the field. Use HTTPS: the payload contains buyer names, email addresses and ticket links.
3. Optionally add a Description of up to 255 characters. It names the webhook in the list; without one the list shows the URL's host.
4. Under Event types, leave All events switched on to receive everything, including any type added later. To receive less, switch it off and untick the types you do not want in the list that appears. Unticking every type saves the same thing as All events, so use Disable to silence a webhook instead.
5. Click Add Webhook. The signing secret, a 64-character hex string, is shown once at the top of the section with a copy button. Store it before you leave the page: it cannot be displayed again.
6. Press Test 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 is one row: its description or, without one, the URL's host, marked Enabled or Disabled, then its URL, then the event types it receives (the first three and a count of the rest, or All events) and when it was last triggered. Three actions sit at the end of the row.

Event Types

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

Drafts never fire an event webhook

Saving, cancelling or deleting a draft event sends nothing. The first delivery for a draft is the event.created you get when it is published.

Group orders send one delivery per ticket holder

When one buyer checks out for several named guests, each row in the order gets its own sale.* delivery. The primary row carries the totals for the whole group; the guest rows report payment_amount as 0 so you do not count the money twice. Use is_primary and group_id in the payload to tell them apart.

A purchase that covered several events carries order_id as well, shared by every row in the order, with is_order_primary set on the one row that anchors it. Money is still reported per group, not per order, so summing payment_amount across an order_id gives the order total without double-counting.

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.*, installment.* and ticket.* the data object is the sale object the Sales API returns, and for event.* it is the event object the Events API returns, 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, order_id, is_order_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.

Record IDs are the same encoded strings the API uses, so an id from a payload can go straight into an API path. Timestamps are ISO 8601 in UTC, and an event's starts_at is UTC in Y-m-d H:i:s, as in the API. Every event payload carries is_cancelled and cancelled_at, which is how an event.updated sent when a cancelled event is restored can be told from any other update.

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 (a Y-m-d date) and next_amount. A declined attempt has no reference; it carries error, attempt, is_final and next_attempt_at in its place.
• 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 Edit on a webhook and then View recent deliveries to see what each attempt got back. The list shows the status your endpoint returned and how long it took, not the response body, so return a status code that tells the failures apart.

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