Set GitHub webhook

POST

apps

{app_id}

deploy

webhook

Set GitHub Webhook

curl --request POST \
  --url https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "access_token": "<string>"
}
'

import requests

url = "https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook"

payload = { "access_token": "<string>" }
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({access_token: '<string>'})
};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'access_token' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook"

	payload := strings.NewReader("{\n  \"access_token\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"access_token\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"access_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
    "status": "success",
    "response": {
        "webhook": "https://api.squarecloud.app/v2/git/webhook/<webhook-code>"
    }
}

string

required

The API key for your account. You can find this in your account settings.

Requires an API key with the apps:deploy scope. This endpoint connects an application to a GitHub repository the classic way: generate a personal access token (ghp_* or the fine-grained github_pat_* format) and Square Cloud returns a unique webhook URL to register on that repository so pushes trigger a deploy. Sending access_token: "@" instead removes the existing webhook and access token from the application. Configuring or removing a webhook invalidates the cached response from Get Current Deployment. Calls are rate limited to 5 per 60 seconds per user, and on workspace-shared applications the caller needs the admin role or ownership. To review deploy attempts triggered by this webhook, use List Deployments. A webhook and a GitHub App link can be configured on the same application at the same time: setting up one does not remove the other.

Parameters

string

required

The ID of the application. You can find this in the URL of your application’s dashboard.

string

required

The access token for your GitHub repository. You can find this in your GitHub Tokens Classic

Response

string

Indicates whether the call was successful: success if it was, error if not.

object

The contents of the response.

Show Toggle object

string

The URL of the webhook.

{
    "status": "success",
    "response": {
        "webhook": "https://api.squarecloud.app/v2/git/webhook/<webhook-code>"
    }
}

Common errors

Code	HTTP	Meaning
`INVALID_ACCESS_TOKEN`	400	`access_token` is not `@` and doesn’t match the `ghp_`/`github_pat_` GitHub token format.

Webhook deliveries

GitHub sends each push to the webhook URL (POST https://api.squarecloud.app/v2/git/webhook/{webhook}). The reply is plain text (text/plain) that says whether a deploy was queued, so the Recent Deliveries list of the webhook on GitHub shows what happened to each push. Only the 429 replies with JSON (KEEP_CALM). A 200 is sent only after the deploy was stored in the queue:

Deploy queued: commit 1a2b3c4 of 'main' will be deployed shortly.

Every other reply ends with Nothing was deployed.

HTTP	Meaning
202	The push is for another branch than the webhook’s `?branch=`, for example: `Push received but not queued: it is for 'dev', and this webhook only deploys 'main'. Nothing was deployed.`
202	`GIT_REF_NOT_SUPPORTED`: the push is for a tag or another ref outside `refs/heads/`. Tags are never deployed.
202	`GIT_BRANCH_DELETED`: the push deletes a branch (`deleted: true`, or an `after` made only of zeros).
400	The webhook URL or the payload is invalid, for example a `ping` event instead of a `push`.
404	`Unknown webhook: it is not linked to any application (it may have been regenerated). Nothing was deployed.`
413	The payload is larger than GitHub’s own webhook limit.
415	The webhook does not send `application/json`. Set the content type to `application/json` in the webhook settings on GitHub.
429	Too many pushes in a short time (`KEEP_CALM`): each webhook accepts 1 push per 15 seconds.
503	A temporary failure on our side kept the deploy from being stored.

Every 202 is answered before the rate limit, so it doesn’t use up the webhook’s limit of 1 push per 15 seconds. A release sent with git push --follow-tags, or a merged pull request whose branch GitHub deletes automatically, no longer holds back the deploy of the branch push that arrives with it. For a tag or a deleted branch, the reply starts with its code, as shown on GitHub in Settings > Webhooks > Recent Deliveries, in the Response tab:

GIT_REF_NOT_SUPPORTED: Push received but not queued: 'refs/tags/v1.2.0' is not a branch (tag pushes are not deployed). Nothing was deployed.
GIT_BRANCH_DELETED: Push received but not queued: it deletes the branch 'feature/login'. Nothing was deployed.

If a delivery shows 503, redeliver it on GitHub in Settings > Webhooks > Recent Deliveries, or push again.

CLI: squarecloud app deploy webhook
SDKs: api.apps.deploys.setWebhook() (JavaScript), client.apps.deploys.set_webhook() (Python), c.Apps.Deploys.SetWebhook() (Go)

Set GitHub Webhook

curl --request POST \
  --url https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "access_token": "<string>"
}
'

import requests

url = "https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook"

payload = { "access_token": "<string>" }
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({access_token: '<string>'})
};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'access_token' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook"

	payload := strings.NewReader("{\n  \"access_token\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"access_token\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/deploy/webhook")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"access_token\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
    "status": "success",
    "response": {
        "webhook": "https://api.squarecloud.app/v2/git/webhook/<webhook-code>"
    }
}

Get started

Account

Applications

Databases

Workspaces

AI

Parameters

Response

Common errors

Webhook deliveries

​Parameters

​Response

​Common errors

​Webhook deliveries

​Related

Parameters

Response

Common errors

Webhook deliveries

Related