Webhooks Guide

The webhooks are free to use, but it costs money to run and maintain, if you can, please contribute.

• The following webhook types are available:
• newBasho - contains start/end date and bashoId. Sent once when a new banzuke is released - typically 2 weeks before the start of the basho.
• newMatches - contains an array of match objects from makuuchi only. Sent whenver a new torikumi is discovered - typically after 18:00 JST each day of a basho.
• matchResults - contains an array of match objects from makuuchi only containing all match details including the winner and winnerId. Sent once per at day 18:15 JST.
• endBasho - contains the basho object with the yusho and special prize details included. Send once when the basho concludes at 18:15 JST on the final day.
• If you want the banzuke, or match data from other divisions, use the webhook as a trigger for your application to fetch from sumo-api standard endpoints.
• Other types can be added upon request.
• When a webhook is issued by sumo-api a POST request will be sent to the subscribed endpoints. Please see the details of the requests below:
• Return a 204 response from your webhook endpoint to acknowledge reciept of the webhook.
• A webhook sent from sumo-api will always contain the following header: X-Webhook-Signature
  This header is derived from your secret and the payload. Please use this to verify that this is a genuine request from the sumo-api.
• Verification example snippet in Golang

  hmacHash := hmac.New(sha256.New, yourSecret)
  hmacHash.Write([]byte(url))
  hmacHash.Write(body)
  calculatedSignature := hex.EncodeToString(hmacHash.Sum(nil))
  if incomingHeaderSignature != calculatedSignature {
    //invalid signature
  }

• The webhook body will contain a JSON object in the following format:
  

  {
    "type":"webhook type (see list)",
    "payload":"some JSON object depending on the type. Execute tests to see the formats"
  }

• How to Subscribe to webhooks
  • POST /api/webhook/subscribe
  • Body of request must contain a valid JSON object in the following format:
    

    {
      "name":"someUniqueIdentifier",
      "destination":"http://www.yourdomain.com/webhookIngestionEndpoint",
      "secret":"your secret to encode the response",
      "subscriptions":{
        "hookType":true,
        "anotherHookType":true
      }
    }

• How to modify your subscription to webhooks
  • PATCH /api/webhook/subscribe
  • Body of request must contain a valid JSON object in the following format:
    

    {
      "name":"someUniqueIdentifier",
      "destination":"http://www.yourdomain.com/webhookIngestionEndpoint",
      "secret":"your secret to encode the response",
      "subscriptions":{
        "hookType":true,
        "anotherHookType":false
      }
    }

  • If the provided name and secret do not match, your update will fail with 400 error
• How to delete your subscription to webhooks
  • DELETE /api/webhook/subscribe
  • Body of request must contain a valid JSON object in the following format:
    

    {
      "name":"someUniqueIdentifier",
      "secret":"your secret to encode the response",
    }

  • If the provided name and secret do not match, your delete will fail with 400 error
• How to test webhooks subscriptions
  • POST /api/webhook/test?type=validWebhookType
  • Body of request must contain a valid JSON object in the following format:
    

    {
      "name":"someUniqueIdentifier",
      "destination":"http://www.yourdomain.com/webhookIngestionEndpoint",
      "secret":"your secret to encode the response",
      "subscriptions":{
        "validWebhookType":true,
      }
    }

  • The test hooks will always provide the same dataset from the 202311 basho.
  • The type in the URL and in the subscriptions object must match.