Webhooks

Introduction

Webhooks allow you to listen to certain events on Toornament. When one of those events happen, a HTTP POST is sent to your configured webhook URL.

Concept

A webhook is linked to an application. You can find the list of your webhooks on the Applications page.

Example of a webhook
{
    "name": "My webhook",
    "url": "http://toornament.com/webhook",
    "enabled": true
}
Example of a subscription
{
    "event_name": "registration.info_updated",
    "scope": "tournament",
    "scope_id": "842693950880972836"
}

First you need to define a webhook (see webhook endpoint). Each webhook subscription (see subscription endpoint) has specific scope and scope_id parameters used to limit the entity events the webhook listens to.

Available Webhook Scopes

The Toornament Webhook API currently support the following webhook scopes:

  • tournament
    listens to a specific tournament. The scope_id is the tournament_id.

Event Names

Registration

  • registration.created
     

    Triggers when a registration is created.

  • registration.info_updated
     

    Triggers when information of a registration is updated.

  • registration.accepted
     

    Triggers when a registration status becomes accepted.

  • registration.refused
     

    Triggers when a registration status becomes refused.

  • registration.reset
     

    Triggers when a registration status becomes pending.

  • registration.cancelled
     

    Triggers when a registration status becomes cancelled.

  • registration.deleted
     

    Triggers when a registration is deleted.

Participant

  • participant.created
     

    Triggers when a participant is created.

  • participant.info_updated
     

    Triggers when information of a participant is updated.

  • participant.checked_in
     

    Triggers when a participant is checked-in.

  • participant.unchecked_in
     

    Triggers when a participant is unchecked-in.

  • participant.deleted
     

    Triggers when a participant is deleted.

Tournament settings

  • tournament.registration_opened
     

    Triggers when a tournament registration is opened.

  • tournament.registration_closed
     

    Triggers when a tournament registration is closed.

  • tournament.check_in_opened
     

    Triggers when a tournament check-in is opened.

  • tournament.check_in_closed
     

    Triggers when a tournament check-in is closed.

Payload

The following information is passed along in the raw body of the post request of the webhook (json encoded):

Example
{
    "name": "registration.created",
    "object_id": "375143143408309123",
    "object_type": "registration",
    "scope": "tournament",
    "scope_id": "842693950880972837",
    "triggered_at": "2015-12-31T00:00:00+00:00"
}
  • name
    string

    Event name.

  • object_type
    string

    Entity type concerned by the event.

  • object_id
    string

    Entity id concerned by the event.

  • scope
    string

    Scope concerned by the event.

  • scope_id
    string

    Scope id concerned by the event.

  • triggered_at
    datetime

    Timestamp of the event trigger in second.

    Format: RFC 3339 (combined date, time and utc offset)

Available Object Types
  • registration

    You can retrieve the registration on the organizer registration endpoint. The object_id is the registration_id.

    https://api.toornament.com/organizer/v2/tournaments/{scope_id}/registrations/{object_id}
  • participant

    You can retrieve the participant on the organizer participant endpoint. The object_id is the participant_id.

    https://api.toornament.com/organizer/v2/tournaments/{scope_id}/participants/{object_id}
  • tournament settings

    You can retrieve the tournament on the organizer tournament endpoint. The object_id is same as scope_id.

    https://api.toornament.com/organizer/v2/tournaments/{scope_id}

Security

Webhook URL legitimation

To ensure your webhook URL is a legit URL, a HTTP HEAD will be sent with the X-Webhook-Secret header. To validate your webhook, the response to this request must return a 200 HTTP Response with the same X-Webhook-Secret header. Save the X-Webhook-Secretheader as you will need it for payload validation.

Payload Validation

In each HTTP POST webhook, a X-Webhook-Signature header is added to the request to ensure that payload has not been altered. To validate the body content you need to concatenate the body response with the X-Webhook-Secret header and hash the result with sha256. The result string must be the same as the X-Webhook-Signature.

Retry policy

If the Toornament servers can not contact the webhook URL, the servers will try to send the data again during the next 24 hours.

So we can not ensure the event payloads will be delivered in the correct order. To prevent any error, we recommend you retrieve the entity concerned by the event to make sure you have its latest state.