Ball by Ball Push via Webhook
Ball by Ball Push via Webhook
Get real-time notifications for ball updates and corrections (only for live matches). Call the Ball by Ball API for detailed delivery information.
Configuring your Console
Follow the instructions below to receive automated cricket match updates in your Webhook URL.
- Login to your Roanuz Sports Console and from the Dashboard, click on Push Configuration and select the Webhook Option.
- Now, in the text boxes, paste your Webhook URLs to which you want the data to be delivered automatically.
- Make sure to set up your webhook URL to handle the data correctly. A sample code has been provided under the “Handling the data received” section.
Scenarios
After configuring your console, this section details the notifications from the Ball by Ball Push API. It explains the types of updates you’ll receive, whether they relate to ball events or other match changes. For specific ball details, you’ll need to use the Ball by Ball API.
Non-Ball Match Update
When a match update occurs that isn't related to a ball (e.g., toss or squad changes), you'll receive a notification with the ball field as null. The push reason will be "Other" and the match_push_kind will also be "Other."
Non-Ball Match Update
{
"sport": "cricket",
"data_kind": "match-entry-update",
"data": {
"matchkey": "matchkey",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Other",
"ts": 1234567890
}
}
{
"sport": "cricket",
"data_kind": "match-entry-update",
"data": {
"matchkey": "matchkey",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Other",
"ts": 1234567890
}
}
New Ball Entered
When a new ball is delivered, the notification will include the ball details, such as ball_key, over, and batting_order. The push_reason will be "NewOrLast" and the match_push_kind will be "Ball."
2. New Ball Entered
{
"sport": "cricket",
"data_kind": "match-entry-update",
"data": {
"matchkey": "matchkey",
"ball": {"ball_key": 1049280, "over": 1, "batting_order": 2, "is_delete": false},
"push_reason": "NewOrLast",
"match_push_kind": "Ball",
"ts": 1234567890
}
}
{
"sport": "cricket",
"data_kind": "match-entry-update",
"data": {
"matchkey": "matchkey",
"ball": {"ball_key": 1049280, "over": 1, "batting_order": 2, "is_delete": false},
"push_reason": "NewOrLast",
"match_push_kind": "Ball",
"ts": 1234567890
}
}Ball Updated (Not Last Ball)
If an earlier ball in the match is updated (e.g., umpire correction), the notification will include the ball's details, and the push_reason will be "Update" with match_push_kind as "Ball."
3. Ball Updated (Not Last Ball)
{
"sport": "cricket",
"data_kind": "match-entry-update",
"data": {
"matchkey": "matchkey",
"ball": {"ball_key": 1049280, "over": 1, "batting_order": 2, "is_delete": false},
"push_reason": "Update",
"match_push_kind": "Ball",
"ts": 1234567890
}
}
{
"sport": "cricket",
"data_kind": "match-entry-update",
"data": {
"matchkey": "matchkey",
"ball": {"ball_key": 1049280, "over": 1, "batting_order": 2, "is_delete": false},
"push_reason": "Update",
"match_push_kind": "Ball",
"ts": 1234567890
}
}Ball Deleted
When a ball (either the last ball or an earlier one) is deleted, you’ll receive a notification where is_delete is true and the push_reason is "Other."
4. Ball Deleted
{
"sport": "cricket",
"data_kind": "match-entry-update",
"data": {
"matchkey": "matchkey",
"ball": {"ball_key": 1049280, "over": 1, "batting_order": 2, "is_delete": true},
"push_reason": "Other",
"match_push_kind": "Ball",
"ts": 1234567890
}
}
{
"sport": "cricket",
"data_kind": "match-entry-update",
"data": {
"matchkey": "matchkey",
"ball": {"ball_key": 1049280, "over": 1, "batting_order": 2, "is_delete": true},
"push_reason": "Other",
"match_push_kind": "Ball",
"ts": 1234567890
}
}Ball by Ball Push - Updates Subscribe
TERMINAL
pip install requests
pip install requestsball_by_ball_updates.py
import requests
project_key = 'YOUR_PROJ_KEY'
token = 'YOUR_ACCESS_TOKEN'
match_key = 'ausind_2020_odi01'
url = "https://api.sports.roanuz.com/v5/cricket/{}/match/{}/updates-subscribe/".format(project_key,match_key)
headers = {
'rs-token': token
}
payload = {
'method': "web_hook"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
import requests
project_key = 'YOUR_PROJ_KEY'
token = 'YOUR_ACCESS_TOKEN'
match_key = 'ausind_2020_odi01'
url = "https://api.sports.roanuz.com/v5/cricket/{}/match/{}/updates-subscribe/".format(project_key,match_key)
headers = {
'rs-token': token
}
payload = {
'method': "web_hook"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())Changes in Match Related Data (e.g., Name Change)
This scenario sends an update to indicate changes in the match data (like the name or other metadata). The API captures the timestamp (
ts), match key, and specific push reason (e.g., a name change).Changes in Match Related Data
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Info",
"ts": 1733148565
}
}
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Info",
"ts": 1733148565
}
}Toss Update
This event indicates that the toss has occurred, and the relevant data about it is being updated. The API doesn't include a specific ball, but it updates the
match_push_kind as "Toss" to reflect the event.Toss Update
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Toss",
"ts": 1733148590
}
}
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Toss",
"ts": 1733148590
}
}Play Status Update
This API call signals changes in the current play status of the match, such as when a match is in play, a delay occurs, or any other status-related change. It uses the
match_push_kind of "Play."3. Play Status Update
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Play",
"ts": 1733148628
}
}
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Play",
"ts": 1733148628
}
}Squad Update
This event notifies any changes to the squad of players participating in the match. It sends information about updates in the team lineup or replacements. No ball-related details are provided in this case.
4. Squad Update
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Squad",
"ts": 1733148670
}
}
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Squad",
"ts": 1733148670
}
}Review Update (Pre, Post, Match Validation)
This update involves any review decisions or changes during or after the match, such as when the umpire refers to the third umpire for a decision. The
match_push_kind is set to "Review."6. Review Update (Pre, Post, Match Validation)
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Review",
"ts": 1733148707
}
}
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Review",
"ts": 1733148707
}
}Result Update
This API sends a message when the match result is determined. It doesn't include ball-by-ball data but focuses on the final outcome, whether it's a win, loss, or draw.
7. Result Update
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Result",
"ts": 1733148721
}
}
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Result",
"ts": 1733148721
}
}Reward Update (Player of the Match)
This update provides information on the "Player of the Match" award. It includes the match key and a timestamp for when the award is given.
8. Reward Update (Player of the Match)
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Reward",
"ts": 1733148725
}
}
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Reward",
"ts": 1733148725
}
}Other Changes (Miscellaneous Updates)
This event is a catch-all for any changes that don't fall under the predefined categories. It includes other match details, updates, or corrections that need to be pushed to clients.
9. Other Changes (Miscellaneous Updates)
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Other",
"ts": 1733148680
}
}
{
"sport": "cricket",
"data_kind": "match-detail-update",
"data": {
"matchkey": "match_key",
"ball": null,
"push_reason": "Other",
"match_push_kind": "Other",
"ts": 1733148680
}
}Subscription Type
You can subscribe to the Update Subscription, which ensures that the match data has been confirmed and cached, providing high-assurance updates for each ball and any match changes.
Update Subscription
1.Trigger: When the match data is confirmed and cached.
- Notification: You’ll get a notification only after the ball data is confirmed as updated and recached. This is ideal for high-traffic or high-importance matches.
- Data Type:
match-related-update
Handle the data received
Once successfully set up, Roanuz Cricket API servers will automatically start pushing data to your systems as the match progresses. The sample snippet below demonstrates how to handle the data once it is pushed by the server.
TERMINAL
pip install flask
pip install flaskwebhook_handle_data.py
from flask import Flask, request
import gzip
import io
import json
app = Flask(__name__)
@app.route('/', methods=['POST'])
def hello():
print("Received")
c_data = io.BytesIO(request.data)
text_data = gzip.GzipFile(fileobj=c_data, mode='r')
byte_str = text_data.read()
dict_str = byte_str.decode("UTF-8")
mydata = json.loads(dict_str)
print(mydata)
print("____")
return 'Hello, World! {}'
from flask import Flask, request
import gzip
import io
import json
app = Flask(__name__)
@app.route('/', methods=['POST'])
def hello():
print("Received")
c_data = io.BytesIO(request.data)
text_data = gzip.GzipFile(fileobj=c_data, mode='r')
byte_str = text_data.read()
dict_str = byte_str.decode("UTF-8")
mydata = json.loads(dict_str)
print(mydata)
print("____")
return 'Hello, World! {}'Unsubscribe from Ball by Ball Push
If, for any reason, you wish to opt-out of automatic push updates for the Ball by Ball notifications, you can easily unsubscribe.
Ball by Ball Push - Unsubscribe
TERMINAL
pip install requests
pip install requestsball_by_ball_updates_unsubscribe.py
import requests
project_key = 'YOUR_PROJ_KEY'
token = 'YOUR_ACCESS_TOKEN'
match_key = 'ausind_2020_odi01'
url = "https://api.sports.roanuz.com/v5/cricket/{}/match/{}/updates-unsubscribe/".format(project_key,match_key)
headers = {
'rs-token': token
}
payload = {
'method': "web_hook"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
import requests
project_key = 'YOUR_PROJ_KEY'
token = 'YOUR_ACCESS_TOKEN'
match_key = 'ausind_2020_odi01'
url = "https://api.sports.roanuz.com/v5/cricket/{}/match/{}/updates-unsubscribe/".format(project_key,match_key)
headers = {
'rs-token': token
}
payload = {
'method': "web_hook"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
