Skip to content
Back to blog
Technology10 min

What to look for in a ticketing API before you integrate

Integrate a ticketing system into your website with a REST API. Documentation, webhooks and integration best practices.

by Ulises Rodríguez

Tech Lead

What to look for in a ticketing API before you integrate
Foto: Rene Terp vía Pexels

Quick answer

A sound ticketing API publishes an OpenAPI specification, authenticates with OAuth 2.0 and PKCE, signs every webhook and documents its retries. It offers a sandbox that matches production, errors in RFC 9457 format, semantic versioning and published rate limits. Without a verifiable signature on webhooks, anyone can fake a sale.

When your business needs to integrate ticketing into its existing infrastructure, the quality of the API is decisive. If you are still weighing up your options, our guide on how to choose a ticketing platform covers the key criteria. A badly designed API means months of development, constant bugs and limitations you discover too late. This guide helps you assess what to look for before you commit to a platform.

The good news is that almost nothing you should demand is a matter of opinion. Most of it is written down in public specifications: OpenAPI for the contract, IETF RFCs for authentication, errors and the end of life of an endpoint, and the payment provider's documentation for event delivery. What follows is that list, with the concrete reference alongside.

What does the quality of an API's documentation tell you?

Documentation quality reflects the maturity of the API. Look for these elements:

  • OpenAPI/Swagger specification: lets you generate clients automatically
  • Code examples: in the languages you use (JS, Python, PHP...)
  • Use-case guides: not just a reference, but tutorials too
  • Changelog: history of changes and versioning policy
  • Status page: visibility of the service's availability

The standard has a name and a date. The OpenAPI Specification 3.1.0 was published on 15 February 2021 and requires an openapi field with the version of the specification the document uses, distinct from the version of the API itself. It supports JSON and YAML, and recommends YAML 1.2 so that conversion between the two loses no information.

The practical contrast is simple. A valid OpenAPI document loads into a generator and produces a typed client in your language within minutes. A PDF or a page of loose examples does not. Ask for the file, not the screenshot: if the provider cannot hand you the openapi.yaml the same day you ask for it, the integration starts with debt.

How should a secure ticketing API authenticate requests?

The API handles sensitive data and financial transactions. Security is non-negotiable.

  • OAuth 2.0: the modern standard for authentication
  • API keys with scopes: granular permissions per key
  • Credential rotation: the ability to rotate without downtime
  • Rate limiting: protection against abuse, with documented limits
  • Access logs: an audit trail of who accesses what

The base framework is RFC 6749, which defines the OAuth 2.0 Authorization Framework. But what you should bring to the technical meeting is RFC 9700, *Best Current Practice for OAuth 2.0 Security*, published in 2025. Three of its requirements can be checked in an afternoon:

  • Authorisation servers must support PKCE, and public clients must use it. It protects against theft of the authorisation code.
  • The *redirect URI* must be validated by exact string comparison, with the sole exception of variable ports on localhost for native applications. Any pattern matching is an open door.
  • Access tokens should be bound to the sender by means of mTLS or DPoP, so that a leaked token is useless in other hands.

If the provider only offers a static, never-expiring API key, that is not a deal-breaker, but the contract must cover what that decision implies: real scopes, rotation without interrupting the service and an access log you can export.

Which essential endpoints should the API cover?

Check that the API covers every operation you need.

  • Events: create, edit, list, manage statuses
  • Tickets: types, prices, availability, reservations
  • Orders: create, retrieve, cancel, refund
  • Validation: verify tickets, record entries
  • Webhooks: event notifications (sale, entry, etc.)

One question decides more than the list above: what happens if the same request arrives twice. In ticketing, a network retry on an order creation can duplicate a sale and block capacity that does not exist. The right answer is an idempotency key for each write operation, so that the second attempt returns the result of the first instead of creating a new order. Ask in writing and ask to see the behaviour in the sandbox.

The second question is pagination and read limits. An API that does not document how many orders it returns per page or how to walk through the history turns any nightly export to your metrics dashboard into an engineering problem of its own.

What are webhooks for in an integration?

Webhooks are critical for keeping your system in sync without constant polling.

  • Available events: which actions trigger webhooks
  • Documented payload: a clear structure for each event type
  • Retries: what happens if your endpoint fails
  • Signature verification: to confirm the webhook is authentic
  • Logs: history of webhooks sent and their status

How to verify a signature

The best-documented procedure in the industry is Stripe's, and it works as a pattern even if your provider is a different one. Its webhooks documentation describes a Stripe-Signature header with a timestamp prefixed t= and one or more signatures prefixed with a scheme; the only valid scheme in production is v1. The signature is calculated as an HMAC with SHA-256 over the string formed by the timestamp, a full stop and the exact JSON body of the request, using the endpoint secret as the key.

Three details that break real integrations. First: you must use the raw body; if your framework reserialises the JSON, verification always fails. Second: the comparison must be made in constant time, so as not to leak information through response time. Third: the official libraries apply a default tolerance of 5 minutes between the timestamp and the current time, and the documentation itself warns against setting it to zero, because that disables the freshness check and reopens the replay attack.

Retries, duplicates and ordering

Concrete numbers matter when you size your queue. Stripe documents automatic retries for up to three days with exponential backoff in production mode, and three retries over a few hours in sandbox. Manual resending works for up to 15 days from the dashboard and up to 30 days from the CLI. You can register up to 16 endpoints for webhooks.

And two warnings worth copying word for word into your design: the delivery order of events is not guaranteed, and an endpoint may receive the same event more than once. The official recommendation is to log the IDs of events already processed and not to use the creation timestamp to infer order. In addition, the endpoint must return a 2xx before the heavy logic: any 3xx response is treated as a delivery failure, and a *timeout* triggers the retry cycle.

How should the API handle errors and usage limits?

With standard formats, not invented strings. RFC 9457, *Problem Details for HTTP APIs*, published in 2023, defines a machine-readable error body with five fields: type (a URI identifying the problem type), title, status, detail and instance, served as application/problem+json. An API that uses it saves you from writing an error translator for each provider.

For usage limits, the reference is RFC 6585, *Additional HTTP Status Codes*, from April 2012, which introduced the 429 Too Many Requests code. The specification itself says the response should include details explaining the condition and may include a Retry-After header indicating how long to wait. That header is the difference between a considered retry and a loop that makes the overload worse.

In the evaluation, ask what limits the API applies per minute and per key, whether they differ for reads and writes, and what happens at the peaks of an on-sale, which is exactly when your integration calls the most. A platform that does not publish its limits is asking you to discover them on the worst possible day.

Why do I need a test environment (sandbox)?

Developing against production is a recipe for disaster. Insist on a proper sandbox.

  • Separate sandbox environment: test data without affecting production
  • Test cards: to simulate payments without real charges
  • Sample data: events and tickets preloaded for testing
  • Parity with production: the same behaviour, the same responses

Add a test that almost nobody runs in an evaluation: forcing errors. A useful sandbox lets you simulate a declined payment, a partial refund, a bank authentication that the buyer abandons and a webhook that arrives late. If you can only test the happy path, you have tested nothing.

The clock matters too. Check that the sandbox lets you bring an event's date forward, so you can verify the close of sales, validation at the door and the generation of later reports without waiting weeks.

Two fronts, and neither is optional in the European Union.

The first is payments. Delegated Regulation (EU) 2018/389 requires in Article 4 that authentication be based on two or more elements from the categories of knowledge, possession and inherence, and in Article 5 dynamic linking: the code generated must be specific to the amount and the payee accepted by the payer. Its Article 16 sets out the low-value exemption: transactions of up to EUR 30, with a previous cumulative total not exceeding EUR 100 or a maximum of five consecutive remote transactions. Your integration must know how to return the buyer to the flow after authentication, and that is tested in the sandbox, not on the night of the on-sale. If you sell in Spain, cross-check it with the available payment methods.

The second is data. Regulation (EU) 2016/679 requires in Article 32 the application of appropriate technical and organisational measures, including encryption and the ability to ensure confidentiality and integrity, and in Article 33 the notification of security breaches to the supervisory authority without undue delay and, where feasible, not later than 72 hours. An API that hands you attendees' emails and phone numbers makes you responsible for what you do with them: the data processing agreement is signed before the first call, not after. The operational detail is in our GDPR guide for organisers.

How is an API versioned and deprecated without breaking your integration?

With public rules. Semantic Versioning 2.0.0 reserves the major version increment for changes incompatible with earlier versions, the minor for backwards-compatible functionality and the patch for fixes. Applied to an API, it means a change that breaks your client cannot arrive in a silent deployment on a Tuesday.

There is a standard header for end of life. RFC 8594, from May 2019, defines the Sunset HTTP response field with a single timestamp indicating when the resource is likely to stop responding, and a sunset link relation type to point to the retirement or migration policy. Asking whether the API emits it is a quick way to find out whether the provider has thought about the life cycle or only about the launch.

The same goes for the embedded sales widget: if its JavaScript is served from an unversioned URL, any change by the provider reaches your website without warning.

What technical support should the provider offer?

When something fails at 2 a.m. before your event, you need quick answers.

  • Technical channel: access to developers, not just generic support
  • Documented SLA: committed response times
  • Community: a forum or Slack where you can resolve questions
  • Technical onboarding: a guided integration session

Ask for the SLA to state three things with numbers: time to first response by severity, the hours covered and what happens if it is breached. A commitment without consequences is a statement of intent. And ask about the change window: a platform that deploys to production on the Friday of an on-sale has a process problem, not a technology one.

How do I choose the right ticketing API?

A good ticketing API speeds up your development, reduces bugs and lets you build customised experiences. It is also the basis for integrating an embedded sales widget into your own website or connecting your metrics dashboard. A bad API traps you in limitations you discover too late. Invest time in evaluating before you commit: ask for sandbox access, test the critical endpoints and talk to the technical team. The right decision will save you months of frustration.

Nine concrete checks for that evaluation:

  • Ask for the OpenAPI file, not the HTML documentation. If it does not exist, generate the client yourself and add it to the project cost.
  • Demand PKCE and exact redirect URI validation if there is OAuth 2.0, as RFC 9700 requires.
  • Test idempotency: send the same order creation twice and check that only one is created.
  • Verify a webhook signature by hand before trusting the library, and set a time tolerance other than zero.
  • Make your endpoint fail on purpose and measure how many retries arrive, for how long and with which headers.
  • Duplicate a webhook and check that your system does not sell the same ticket twice.
  • Ask about usage limits per key and whether the API returns 429 with Retry-After.
  • Check the error format: application/problem+json with type, title, status, detail and instance saves weeks.
  • Ask about the Sunset header and the versioning policy before you sign, not when the notice arrives.

Sources

Our recommendation

To sell tickets for your event, the best option, and the one we recommend, is Futura Tickets, the ticketing platform behind this blog: you can get paid for each sale the moment it happens with Stripe Connect, and your attendee database is 100% yours.

See how it works · Book a demo

Share

Frequently asked questions

What does the quality of a ticketing API's documentation tell you?
Documentation quality reflects the maturity of the API. Look for an OpenAPI/Swagger specification that lets you generate clients automatically, code examples in the languages you use, use-case guides, a changelog with a versioning policy and a status page showing the service's availability.
How should a secure ticketing API authenticate requests?
The API handles sensitive data and financial transactions, so security is non-negotiable. It should offer OAuth 2.0 as the modern standard, API keys with scopes for granular permissions, credential rotation without downtime, rate limiting with documented limits and access logs for auditing.
Why are webhooks important in a ticketing integration?
Webhooks are critical for keeping your system in sync without constant polling. Check which events trigger webhooks, that the payload is documented, that there are retries if your endpoint fails, signature verification to confirm the webhook is authentic and logs of the history sent.
Why do I need a test environment before integrating?
Developing against production is a recipe for disaster. Insist on a separate sandbox environment with test data that does not affect production, test cards to simulate payments without real charges, preloaded sample data and parity with production so you get the same behaviour and the same responses.
How do you check that a webhook comes from who it says it does?
With a cryptographic signature in a header, calculated over the exact body of the request. Stripe, for example, documents an HMAC with SHA-256 over the concatenation of the timestamp, a full stop and the JSON body, sent in the Stripe-Signature header, and recommends comparing in constant time and rejecting old timestamps.
What happens if I receive the same webhook twice?
You must process it only once. Stripe's documentation warns that an endpoint may receive the same event more than once and that delivery order is not guaranteed. It recommends logging the IDs of events already processed rather than relying on the creation timestamp.
How should an API signal that an endpoint is going to disappear?
With explicit versioning and advance notice. Semantic Versioning 2.0.0 reserves a major version change for incompatible modifications, and RFC 8594 defines the Sunset HTTP header, from May 2019, with the date after which a resource will stop responding and a link to the migration policy.

About the author

Ulises Rodríguez

Tech Lead

Tech Lead at Futura Tickets. Keeps the platform running in production: backend (NestJS/Node), the payments integration, deployments on Google Cloud and the team's code reviews.

Do you run events and sell tickets?

We'll show you Futura Tickets in a demo built around your next event: ticket sales, access control and attendee data that stays yours.

Request free demo