Webhooks

Webhooks allow other apps to get real-time notifications of events that occur in Atleta. For example, when a new order is placed, when a registration is reassigned, or when a ticket number is updated.

Overview

1. Create an HTTPS endpoint for the events that you want to be notified about. See below for a complete list of events. At this moment, you can enable the webhook by sending us an e-mail with the endpoint URL and the list of events to subscribe to.
2. As events occur, we will POST the payload of the events in JSON format to the webhook. See the List of events below for a complete overview of available event types and corresponding payload.
3. A single request can contain multiple events, even though the webhook is called real-time. This is because events that occur in a very short time period are grouped together (for example, when ticket numbers are assigned to many registrations).
4. The endpoint should respond with a HTTP 2xx status code within 5 seconds to confirm that the events have been received succesfully.

Best practices

When implementing the webhook endpoint, please take into account the best practices below to make sure that events are processed correctly.

Retries

When the endpoint does not respond with a HTTP 2xx status code within 5 seconds, the request is automatically retried with the same payload. Retries are scheduled after 10 seconds, 1 minute, 10 minutes, 1 hour and 12 hours. After that, the events are not delivered anymore. To avoid hitting the timeout limit, we recommend handling the events asynchronously.

Duplicate events

Webhook endpoints might receive the same events more than once. You should skip previously processed events if handling the same event multiple times might cause problems for your app. For this, every event contains a unique event_id in its payload.

Order of events

Atleta does not guarantee that events are delivered in the order in which they occurred. For example, after quickly cancelling and then recovering a registration, the registration.deactivated event might reach your endpoint before the registration.activated event. You can use the API and registration_id in the event's payload, to retrieve the current status of the registration (active or inactive).

Security

We only support HTTPS webhooks over TLS. If you want to be sure that only Atleta can make requests to the webhook endpoint, you can add a secret parameter to the webhook URL as authentication mechanism.

Example webhook request

List of events

Find below all events that are currently available. A single webhook endpoint can subscribe to multiple events at the same time.

• Event: order.created
  • Occurs when an order is placed. The order can contain new registrations and/or updates to existing registrations.
    • order_id
• Event: order.field_entry.updated
  • Occurs when a field entry of an existing order is updated.
    • field_entry_id
    • order_id
• Event: participant.updated
  • Occurs when a participant is updated (e-mail address, name, adress, phone number, date of birth, gender or nationality).
    • participant_id
• Event: participant.field_entry.updated
  • Occurs when a field entry of an existing participant is updated.
    • field_entry_id
    • participant_id
• Event: purchase.field_entry.updated
  • Occurs when a field entry of an existing purchase is updated.
    • field_entry_id
    • purchase_id
• Event: registration.activated
  • Occurs when a registration is reactivated.
    • registration_id
• Event: registration.deactivated
  • Occurs when a registration is deactivated.
    • registration_id
• Event: registration.reassigned
  • Occurs when a registration is reassigned to a different participant.
    • registration_id
• Event: registration.team.updated
  • Occurs when a participant joins or leaves a team.
    • registration_id
• Event: registration.ticket.updated
  • Occurs when the ticket of a registration is updated.
    • registration_id
• Event: registration.ticket_number.updated
  • Occurs when the ticket number (or ticket number sequence) is updated.
    • registration_id
• Event: registration.time_slot.updated
  • Occurs when the time slot of a registration is updated.
    • registration_id