Skip to content

Billetto API documentation and webhooks guide

How to authenticate, which endpoints to call and how Billetto webhooks deliver ticketing data to your systems in real time. Technical guides for developers building on Billetto.
DEVELOPER HUB

What you can build with the Billetto API

The Billetto API is a REST API that returns JSON. It gives your own code access to the same data that runs your box office: events, ticket types, orders, attendees, ledger entries, booking questions and target groups. Webhooks push changes to you as they happen, so you don't have to poll for them.

Teams use it to sync buyers into a CRM, load sales into a data warehouse, list events on their own website, add members to presale audiences and reconcile payouts in their finance system. This page covers how the API is organised and how webhooks work. The full schema for every endpoint lives in the API reference.

Start here

AUTHENTICATION

Authenticate with an API key pair or OAuth 2.0

API key pairs, for your own account

Use a key pair when your own systems call the API on behalf of your organiser account. Create one in Billetto under Integrations → Developers → API - Key pairs, give it a name that says what it's for (for example "CRM sync" or "Data warehouse"), and send it with every request in the Api-Keypair header.

  • Create a separate key pair per system, so you can revoke one without breaking the others
  • Keep the secret on your server. Never ship it in a browser, mobile app or public repository
  • Revoke and replace a key pair straight away if you think it has leaked

OAuth 2.0, for apps used by other organisers

Use OAuth when you build a product that other Billetto organisers connect to, such as a marketing tool, an event platform or an agency dashboard. OAuth uses the authorization code flow: the organiser signs in to Billetto, approves your app and you receive a token for their account. You never see their password and they can disconnect your app at any time.

Both methods are described step by step in the getting started guide.

Events and ticket types

Read the events on your account with their dates, venues, status and ticket types.

  • GET /organiser/events lists your events
  • Ticket types, prices and availability per event
  • Booking questions you ask buyers at checkout

Typical use

Show your upcoming events on your own website or app, with live availability, and send buyers to the Billetto checkout to pay.

Orders and attendees

Read who bought what, when and for which event.

  • GET /organiser/orders lists orders across your events
  • GET /organiser/events/{event_id}/attendees lists attendees for one event
  • Results come in pages: keep requesting the next page until there are no more

Typical use

Keep buyer records in your CRM up to date, or send attendee lists to a door system or accreditation tool.

Ledger entries and reports

Get the financial detail behind your ticket sales.

  • GET /organiser/ledger_entries lists sales, refunds, fees and payouts
  • A BI report per event with its key sales figures

Typical use

Load revenue into your accounting system or data warehouse and reconcile it with your payouts.

Target groups and members

Write data back to Billetto as well as reading it.

  • Create, update and remove target group members
  • Import whole lists and follow the import status
  • Read a target group and its member count

Typical use

Sync members, subscribers or partner lists from your CRM into Audiences for presales and private offers.

Webhook subscriptions

Manage webhooks in code instead of in the Billetto interface.

  • POST /organiser/webhooks registers an endpoint URL
  • Update or remove an existing webhook
  • Generate a new signing secret for a webhook

Typical use

Register webhooks automatically when a new client or environment is set up, and rotate secrets on a schedule.

Public Event Search

Search the events that are publicly listed on Billetto, across organisers.

  • Query parameters to narrow the results, listed in the reference
  • Every result links to the event page and checkout

Typical use

Media, city guides and partner platforms use it to show what's on, with tickets sold through Billetto.

SEE IT IN ACTION

The Billetto API and webhooks, step by step

APIStep 1: credentials

Create a key pair and make your first request

Open Integrations, go to the Developers tab and create a key pair for the system you are connecting. Copy the secret, add it to your request headers and call an endpoint such as /organiser/orders. The response is JSON you can map straight into your own data model.

  • One key pair per integration, named after the system that uses it
  • JSON responses for events, orders, attendees and ledger entries
  • Revoke a key pair at any time without affecting the others
Open the API reference

AUDIENCESStep 2: write to Billetto

Add contacts to a target group through the API

The Audiences endpoints are the main way to write data into Billetto. Post contacts from your CRM to a target group, or import a whole list and check its status until it is finished. The group is then ready for invitations, presales and private offers.

  • Add, update and remove members one by one
  • Bulk imports with a status you can poll
  • Groups appear in Audiences straight away

WEBHOOKSStep 3: Billetto webhooks

Register a webhook and watch deliveries arrive

Add your endpoint URL on the Developers tab and Billetto generates a signing secret for it. From then on, each order, refund, attendee change or published event is sent to your URL as an HTTP POST with a JSON body.

  • Set up in the interface or with POST /organiser/webhooks
  • A signing secret per webhook, which you can regenerate
  • The Webhooks card shows the URL and API version of each webhook
Read the webhook reference
BILLETTO WEBHOOKS

What Billetto webhooks are and when to use them

A webhook is a URL on your server that Billetto calls when something changes on your account. Instead of asking the API every few minutes whether there are new orders, you get a request the moment an order is placed, refunded or updated.

That makes webhooks the right tool when timing matters: a confirmation in your CRM within seconds, a Slack alert when a VIP ticket sells, or an access system that needs to know about a cancelled ticket before the doors open.

Webhooks or the API?

  • Use webhooks to react to changes as they happen: new orders, refunds, attendee updates and published events
  • Use the API to load history, run a nightly full sync, or fetch details a webhook payload doesn't include
  • Use both for the most reliable set-up: webhooks for speed, a scheduled API sync to catch anything you missed
HOW IT WORKS

How a Billetto webhook delivery works

From the moment a ticket is sold to the moment your system has processed it.
1
REGISTER YOUR ENDPOINT
Add a public HTTPS URL on the Developers tab or through the API, and store the signing secret Billetto gives you.
2
SOMETHING CHANGES
A buyer places an order, a ticket is refunded, an attendee's details are updated or you publish an event.
3
BILLETTO SENDS A POST
Billetto sends an HTTP POST to your URL with a JSON body describing what changed.
4
VERIFY AND RESPOND
Check the request with your signing secret, reply with a 2xx status and process the data in the background.
WEBHOOK BEST PRACTICES

Build a webhook receiver you can rely on

Security

  • Verify every request with the webhook's signing secret before you trust the payload. The webhook reference describes how
  • Only accept HTTPS and keep the secret in server-side configuration, not in your code
  • Regenerate the secret if it may have been exposed, then update your receiver

Reliability

  • Respond fast. Return a 2xx status as soon as the request is verified and do the heavy work in a queue
  • Handle duplicates. Store the IDs you've processed so the same order is never created twice
  • Don't rely on order of arrival. If sequence matters, fetch the latest state of the order from the API
  • Reconcile regularly. A scheduled API sync catches anything your endpoint missed during downtime
Full endpoint documentation

Billetto API reference

The API reference documents every endpoint with its parameters, example requests and response objects. Use it alongside this guide when you start coding: find the resource you need above, then look up its exact fields in the reference.

Webhook resource

Webhook reference

The webhook resource holds the configuration of an endpoint: its URL, the API version it uses and its signing secret. We recommend creating your first webhook in Billetto under Integrations → Developers, then managing it through the API once your set-up grows.

Public events, across organisers

Public Event Search API

The Public Event Search API returns events that organisers have listed publicly on Billetto, across all organisers. It suits media sites, city guides, tourism boards and partner apps that want to show what's on, with each result linking to the Billetto event page where tickets are bought.

API AND WEBHOOK FAQ

Billetto API and webhook questions

Technical questions from developers working with the Billetto API. Something not covered? Talk to our team.

Where do I find my Billetto API key?

Log in to Billetto, open Integrations and go to the Developers tab. Under API - Key pairs you can create a new key pair, see who owns each one and revoke keys you no longer use.

What is the difference between an API key pair and OAuth?

A key pair gives your own systems access to your own organiser account. OAuth 2.0 is for apps that other organisers connect to their Billetto account, so you act on their behalf without handling their login.

Which events can Billetto webhooks send?

Webhooks cover changes to orders, attendees and events, such as new orders, refunds, attendee updates and published events. The webhook reference lists every event and its payload.

How do I verify that a webhook request came from Billetto?

Each webhook has its own signing secret. Use it to check every incoming request before you process it, and reject requests that fail the check. You can generate a new secret for a webhook at any time.

Can I create webhooks through the API?

Yes. You can register, update and remove webhooks with the webhook endpoints, and generate a new signing secret for an existing webhook. Most teams start in the interface and move to the API when they manage several environments.

What should I do if I get an HTTP 429 response?

429 means you are sending too many requests. Wait and retry with an increasing delay, and use webhooks instead of frequent polling to keep your request volume low.

Can I list Billetto events on my own website or platform?

Yes. Use the Public Event Search API for events listed publicly on Billetto, or the organiser events endpoint for your own events. Buyers complete their purchase in the Billetto checkout.

I'm not a developer. Can I still connect Billetto to other tools?

Yes. Google Analytics 4, the Meta Pixel, Zapier and your own payment provider connect without code. See Billetto integrations for what you can set up in a few minutes.

Ready to make your first request?

Create a key pair in Integrations, open the reference and call your first endpoint. If you'd rather connect Google Analytics, the Meta Pixel or Zapier without writing code, start with Billetto integrations.