Webhooks

Introduction

Webhooks allow you to listen to certain events on Toornament. When one of those events happen, an HTTP POST request 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.

Scopes

The Webhook API currently support the following webhook scope:

tournament
Listens to a specific tournament. The scope_id is the tournament_id.
project
Listens to a specific project. The scope_id is the ID of the project.
platform
Listens to a specific platform. The scope_id is the ID of the platform.

Event Names

Registration

Scope: tournament, project, platform

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.payment_pending

Triggers when a registration have a payment in pending.
registration.payment_skipped

Triggers when a registration payment has been skipped.
registration.payment_completed

Triggers when a registration payment has been completed.
registration.payment_refunded

Triggers when a registration payment has been refunded.
registration.payment_failed

Triggers when a registration payment have failed.
registration.deleted

Triggers when a registration is deleted.

Participant

Scope: tournament, project, platform

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 checked out.
participant.deleted

Triggers when a participant is deleted.

Tournament

Scope: tournament, project, platform

tournament.created

Triggers when a new tournament has been created.
tournament.registration_opened

Triggers when a tournament registration process starts.
tournament.registration_closed

Triggers when a tournament registration process ends.
tournament.check_in_opened

Triggers when a tournament check-in process starts.
tournament.check_in_closed

Triggers when a tournament check-in process ends.
tournament.info_updated

Triggers when a tournament information has been updated.
tournament.custom_fields_updated

Triggers when a tournament custom fields has been updated.
tournament.sponsors_updated

Triggers when a tournament sponsors has been updated.
tournament.standing_updated

Triggers when a tournament standing has been updated.
tournament.deleted

Triggers when a tournament has been deleted.

Stage

Scope: tournament, project, platform

stage.created

Triggers when a new stage has been created.
stage.info_updated

Triggers when a stage information has been updated.
stage.structure_updated

Triggers when a stage structure has been updated.
stage.status_updated

Triggers when a stage status has changed.
stage.deleted

Triggers when a stage has been deleted.

User

Scope: platform

user.created

Triggers when a user is created.
user.updated

Triggers when information of a user is updated.
user.email_changed

Triggers when a user changes their email address.
user.deleted

Triggers when a user is deleted.

Team

Scope: platform

team.created

Triggers when a team is created.
team.lineup_changed

Triggers when a team lineup has been changed.
team.disbanded

Triggers when a team is disbanded.

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 seconds.
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/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/participants/{object_id}
```
tournament settings
You can retrieve the tournament on the organizer tournament endpoint with scope to tournament. The object_id is the same as the 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 request 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-Secret header 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.