- tournamentlistens to a specific tournament. The
scope_id
is thetournament_id
.
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.
Available Webhook Scopes
The Toornament Webhook API currently support the following webhook scope:
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 checked out.
- participant.deleted
Triggers when a participant is deleted.
Tournament settings
- 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.
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" }
- namestring
Event name.
- object_typestring
Entity type concerned by the event.
- object_idstring
Entity id concerned by the event.
- scopestring
Scope concerned by the event.
- scope_idstring
Scope id concerned by the event.
- triggered_atdatetime
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 theregistration_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 theparticipant_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 the same as thescope_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.