How to set up webhooks on Race Roster

A webhook is a one-time data send for each instance when a pre-set trigger has been met. Webhooks are often used to send specific information to an external partner at the time of registration. For example, you may automate sending participant information to an external vendor for one of your event's products. This way, the vendor can have a record of each product transaction, along with the participant's information if any action is needed from the vendor.

1. From your event dashboard, you can enable Webhook request settings from the settings overview tab from the lefthand side menu by clicking on the Webhook request settings card available under Add-ons.

2. Once enabled, this setting will permanently be available under your Add-ons tab from the lefthand side menu, so that you may access from there.

3. Click the "+ Create webhook" button to begin configuring the parameters and settings of your first webhook. 

4. Input the following information to configure your webhook: 

• Webhook name
  • The webhook name is for your purposes only
  • It is only displayed within the webhook settings as a way to distinguish between multiple webhooks
• Selecting webhook status
  • Active or inactive
• Endpoint URL
  • The endpoint URL for the webhook from our system
  • This It can make either a GET or POST request to your desired URL
• Request method 
  • POST = Sending and updating new data
  • GET = Retrieving data
• API Key

  • this is generated by default and you may leave it as is, but you may also enter a custom API key if needed

5. Select data tags for the webhook. Click on the dropdown menu under the Add new tag headline, locate a piece of data you want to include in the webhook, and then click the "Add tag" button. Repeat this process until you have specified all the tags you want. The selected tags will be the data fields that are pulled from the participant's transaction and sent to the endpoint URL provided by the third party. Tags can consist of: 

• personal information
• product selections
• answers to registration questions

6. Set the triggers for the webhook. The selected triggers are what will initiate the webhook once the criteria has been met by the participant during registration. Set your triggers so that a new webhook will be sent once the desired action has been met.

7. Click "Save & exit" on the bottom right to apply all edits and finish creating the webhook. 

From here on, as new registrations come in, those which fulfill the triggers will activate the webhook and send data to the endpoint URL.

Validating webhooks 

To validate a webhook that came from Race Roster and belongs to your event, you may decode the base64-encoded string within the authorization header to check that it matches your webhook API key.

1. Receive a POST request sent from Race Roster
2. Read the authorization header from the POST request
3. Decode the Base64 value after "Basic "
   For example, in:

   Basic QVBJX0tFWQ==

   you would decode the Base64 value of

   QVBJX0tFWQ==

4. Confirm that the decoded value matches your API key

Notes:

• webhooks can be sent as JSON files which are lightweight, text-based file formats that can be opened and read through any text editor. 
• webhooks will still send if the event is in draft or demo status
• webhooks will not send from manually adding participants to an event