--- title: "Ticket Fairy Order Webhooks | Full Order Payload Reference" description: "Get the whole order at your own URL each time it changes: buyer, tickets, tables, add-ons, money and answers. Payload fields, signature checks and an example." canonical: "https://www.ticketfairy.com/developers/webhooks" --- # Ticket Fairy Order Webhooks | Full Order Payload Reference Ticket Fairy developer documentation # Receive every order as it changes Ticket Fairy sends the whole order to your URL each time it changes: the buyer, the event, every ticket, table and add-on, the money and the checkout answers. Use it to keep your CRM, access control or reporting up to date without polling. [Set up a webhook](#setup) [See an example payload](#example) This page describes the full order format. For the event API and the agent protocols, read the [Ticket Fairy developer documentation](https://www.ticketfairy.com/developers). Get an example payload ``` $ curl 'https://www.ticketfairy.com/api/v1/webhooks/notification/example?type=order&format=full_order' ``` No key, no sign-in. The response is JSON. ## When you get a delivery You get a delivery with the whole order when one of these things happens: - An order is paid. You get one delivery, after the last ticket in the order becomes valid. - A buyer makes the first payment on a payment plan, and again when they pay the last instalment. - A buyer adds an add-on to an order they already placed. - A ticket holder changes their details. - A ticket is transferred to somebody else. - A ticket is listed for resale, or is sold on resale. - A ticket is refunded or cancelled. - A ticket is checked in, if the event has check-in sync switched on. See the questions at the end of this page. ## Set up a webhook A webhook can cover one brand, one tour or one event. A brand webhook covers every event of that brand. ### In the dashboard 1. Open the brand, tour or event in your Ticket Fairy dashboard. 2. Go to the **Webhooks** page. 3. Add a webhook, enter your URL and choose the **Full order** format. ### With the subscription API Generate a webhook API key in [your account settings](https://manage.ticketfairy.com/account). Send it as a Bearer token to `POST https://www.ticketfairy.com/api/v1/webhooks/subscription`. Set `criteria` to `brand`, `tour` or `event`, and `criteria_id` to its ID. Set `format` to `full_order`. `source` is a short name for your application, in letters, numbers, dashes and underscores. `headers` are sent with every delivery. ### Addresses you need Subscription endpoint, POST to subscribe and DELETE to unsubscribe ``` https://www.ticketfairy.com/api/v1/webhooks/subscription ``` Example payload, GET ``` https://www.ticketfairy.com/api/v1/webhooks/notification/example?type=order&format=full_order ``` Missed orders, GET with a Personal Access Token ``` https://www.theticketfairy.com/api/events/{event_id}/relationships/orders ``` This documentation ``` https://www.ticketfairy.com/developers/webhooks ``` Subscribe ``` $ curl -X POST 'https://www.ticketfairy.com/api/v1/webhooks/subscription' \ -H 'Authorization: Bearer YOUR_WEBHOOK_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "type": "order", "method": "post", "url": "https://example.com/ticket-fairy/orders", "criteria": "event", "criteria_id": "12345", "headers": {"X-Api-Key": "your-own-secret"}, "params": {}, "format": "full_order", "source": "my-crm" }' ``` The response is `201 Created` with the webhook's `id`. Keep it. To remove the webhook, send a `DELETE` request with that ID. The response is `204 No Content`. Unsubscribe ``` $ curl -X DELETE 'https://www.ticketfairy.com/api/v1/webhooks/subscription/WEBHOOK_ID' \ -H 'Authorization: Bearer YOUR_WEBHOOK_API_KEY' ``` ## Delivery and security Each delivery is an HTTPS `POST` to your URL with a JSON body. ### Headers - `Content-Type: application/json` - `X-Signature`, if the event has a signing secret. It is the HMAC-SHA256 of the raw request body, made with the signing secret, as lower-case hex. - The custom headers you set on the webhook. ### Your response - Any 2xx status tells Ticket Fairy that you received the delivery. - Respond quickly, then process the order. Put it on your own queue first. - `410 Gone` removes the webhook. Ticket Fairy sends no more deliveries to it. - Ticket Fairy does not send a failed delivery again. To catch up after a failure, read the answer to [What happens if my endpoint is down?](#questions) ### Check the signature Calculate the HMAC-SHA256 of the raw body with your signing secret. Compare it with `X-Signature` in constant time. Use the bytes you received, not JSON you parsed and encoded again, because a new encoding changes the signature. #### Node.js Node.js with Express ``` const crypto = require('crypto') const express = require('express') const app = express() const secret = process.env.TICKET_FAIRY_SIGNING_SECRET // Read the raw body. The signature is made from the exact bytes you receive. app.post('/ticket-fairy/orders', express.raw({ type: 'application/json' }), (req, res) => { const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex') const received = Buffer.from(req.get('X-Signature') || '', 'utf8') if (received.length !== expected.length || !crypto.timingSafeEqual(received, Buffer.from(expected, 'utf8'))) { return res.sendStatus(401) } const order = JSON.parse(req.body.toString('utf8')) saveForLater(order) // Put the order on your own queue. res.sendStatus(200) }) ``` #### Python Python with Flask ``` import hashlib import hmac import json import os from flask import Flask, request app = Flask(__name__) secret = os.environ["TICKET_FAIRY_SIGNING_SECRET"].encode() @app.post("/ticket-fairy/orders") def receive_order(): raw_body = request.get_data() # The exact bytes you received. expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, request.headers.get("X-Signature", "")): return "", 401 order = json.loads(raw_body) save_for_later(order) # Put the order on your own queue. return "", 200 ``` #### PHP PHP ```