Skip to main content

Webhooks

This page documents the technical details of the webhooks sent from the game engine to your Battlesnake server. They all originate from the Battlesnake Server URL that you provide when creating your Battlesnake in the dashboard.

Battlesnake Details

HTTP Request: GET /

An empty GET request made to the root URL of your Battlesnake, used to load customization, check latency, and verifying successful communications between the game engine and your Battlesnake.

Request Data

None, the game engine will send an empty request body.

Response Properties

PropertyTypeDescription
apiversionstring (required)Version of the Battlesnake API implemented by this Battlesnake. Currently only API version 1 is valid. Example: "1"
authorstring (optional)Username of the author of this Battlesnake. If provided, this will be used to verify ownership. Example: "BattlesnakeOfficial"
colorstring (optional)Hex color code used to display this Battlesnake. Must start with "#", followed by 6 hexadecimal characters. Example: "#888888"
headstring (optional)Head customization. Example: "default"
tailstring (optional)Tail customization. Example: "default"
versionstring (optional)An optional version string for your Battlesnake. This value is not used in gameplay, but can be useful for tracking deployments on your end.

See Customization Guide for more info about changing your Battlesnake's color, head, and tail.

Example Response

200 OK
{
"apiversion": "1",
"author": "MyUsername",
"color": "#888888",
"head": "default",
"tail": "default",
"version": "0.0.1-beta"
}

Game Started

HTTP Request: POST /start

Your Battlesnake will receive this request when it has been entered into a new game that is about to begin. Every game has a unique ID that can be used to allocated resources or data you may need. Your response to this request will be ignored.

Request Data

ParameterTypeDescription
gameobjectGame Object describing the game being played.
turnintegerTurn number (always 0 for new games).
boardobjectBoard Object describing the initial state of the game board.
youobjectBattlesnake Object describing your Battlesnake.

Response Properties

Responses to this request are ignored by the game engine.

Move

HTP Request: POST /move

This request will be sent for every turn of every game that your Battlesnake plays. Use the information provided to determine how your Battlesnake will move on that turn, either up, down, left, or right.

Request Parameters

ParameterTypeDescription
gameobjectGame Object describing the game being played.
turnintegerTurn number for this move.
boardobjectBoard Object describing the initial state of the game board.
youobjectBattlesnake Object describing your Battlesnake.

Response Properties

PropertyTypeDescription
movestringYour Battlesnake's move for this turn. Valid moves are "up", "down", "left", or "right".
shoutstring (optional)An optional message sent to all other Battlesnakes on the next turn. Must be 256 characters or less.

Example Response

200 OK
{
"move": "up",
"shout": "Moving up!"
}

Game Over

HTTP Request: `POST /end``

Your Battlesnake will receive this request whenever a game it was playing has ended. Use it to learn how your Battlesnake won or lost and deallocate any server-side resources. Your response to this request will be ignored.

Request Data

ParameterTypeDescription
gameobjectGame Object describing the game being played.
turnintegerFinal turn number.
boardobjectBoard Object describing the initial state of the game board.
youobjectBattlesnake Object describing your Battlesnake.

Response Properties

Responses to this request are ignored by the game engine.