> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurar webhook do GitHub

> Conecte uma aplicação a um repositório do GitHub com um token de acesso pessoal via POST /v2/apps/{app_id}/deploy/webhook, ou envie @ para remover o webhook.

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

Requer uma chave de API com o [escopo](/pt-br/api-reference/authentication#escopos) `apps:deploy`.

Este endpoint conecta uma aplicação a um repositório do GitHub da forma clássica: gere um token de acesso pessoal (formato `ghp_*` ou o formato refinado `github_pat_*`) e a Square Cloud retorna uma URL de webhook única para registrar nesse repositório, para que pushes disparem um deploy. Enviar `access_token: "@"` remove o webhook e o token de acesso existentes da aplicação.

Configurar ou remover um webhook invalida a resposta em cache de [Obter o deploy atual](/pt-br/api-reference/endpoint/apps/deploy/info). As chamadas são limitadas a 5 por 60 segundos por usuário, e em aplicações compartilhadas em workspace, quem chama precisa da [função](/pt-br/api-reference/endpoint/workspace/members/invite#funções) `admin` ou ser o proprietário. Para revisar as tentativas de deploy disparadas por esse webhook, use [Listar deploys](/pt-br/api-reference/endpoint/apps/deploy/list).

Um webhook e um [vínculo do GitHub App](/pt-br/api-reference/endpoint/apps/deploy/github-app-link) podem ser configurados na mesma aplicação ao mesmo tempo: configurar um não remove o outro.

## Parâmetros

<ParamField path="app_id" type="string" placeholder="ID da Aplicação" required>
  O ID da aplicação. Você pode encontrá-lo na URL da sua aplicação no dashboard.
</ParamField>

<ParamField body="access_token" type="string" placeholder="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" required>
  O token de acesso do seu repositório GitHub. Você pode encontrá-lo nos seus [GitHub Tokens Classic](https://github.com/settings/tokens/new)
</ParamField>

## Resposta

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida: `success` se foi, `error` se não.
</ResponseField>

<ResponseField name="response" type="object">
  O conteúdo da resposta.

  <Expandable title="Alternar objeto">
    <ResponseField name="webhook" type="string">
      A URL do webhook.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={"system"}
  {
      "status": "success",
      "response": {
          "webhook": "https://api.squarecloud.app/v2/git/webhook/<webhook-code>"
      }
  }
  ```
</ResponseExample>

## Erros comuns

| Código | HTTP | Significado |
| - | - | - |
| `INVALID_ACCESS_TOKEN` | 400 | `access_token` não é `@` e não corresponde ao formato de token do GitHub `ghp_*`/`github_pat_*`. |

## Entregas do webhook

O GitHub envia cada push para a URL do webhook (`POST https://api.squarecloud.app/v2/git/webhook/{webhook}`). A resposta é texto puro (`text/plain`) que diz se um deploy foi enfileirado, então a lista **Recent Deliveries** do webhook no GitHub mostra o que aconteceu com cada push. Apenas o `429` responde com JSON (`KEEP_CALM`).

Um `200` só é enviado depois que o deploy foi armazenado na fila:

```text theme={"system"}
Deploy queued: commit 1a2b3c4 of 'main' will be deployed shortly.
```

Todas as outras respostas terminam com `Nothing was deployed.`

| HTTP | Significado |
| - | - |
| 202 | O push é de outra branch que não a do `?branch=` do webhook, por exemplo: `Push received but not queued: it is for 'dev', and this webhook only deploys 'main'. Nothing was deployed.` |
| 202 | `GIT_REF_NOT_SUPPORTED`: o push é de uma tag ou de outra ref fora de `refs/heads/`. Tags nunca geram deploy. |
| 202 | `GIT_BRANCH_DELETED`: o push exclui uma branch (`deleted: true`, ou um `after` só com zeros). |
| 400 | A URL do webhook ou o payload é inválido, por exemplo um evento `ping` em vez de um `push`. |
| 404 | `Unknown webhook: it is not linked to any application (it may have been regenerated). Nothing was deployed.` |
| 413 | O payload é maior do que o próprio limite de webhook do GitHub. |
| 415 | O webhook não envia `application/json`. Defina o content type como `application/json` nas configurações do webhook no GitHub. |
| 429 | Pushes demais em pouco tempo (`KEEP_CALM`): cada webhook aceita 1 push a cada 15 segundos. |
| 503 | Uma falha temporária do nosso lado impediu que o deploy fosse armazenado. |

Todo `202` é respondido antes do limite de taxa, então não gasta o limite de 1 push a cada 15 segundos do webhook. Um release enviado com `git push --follow-tags`, ou um pull request mergeado cuja branch o GitHub exclui automaticamente, não segura mais o deploy do push da branch que chega junto. Para uma tag ou uma branch excluída, a resposta começa com o código, como aparece no GitHub em **Settings > Webhooks > Recent Deliveries**, na aba **Response**:

```text theme={"system"}
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.
```

<Tip>Se uma entrega mostrar `503`, reenvie-a no GitHub em **Settings > Webhooks > Recent Deliveries**, ou faça push novamente.</Tip>

## Relacionados

* CLI: [`squarecloud app deploy webhook`](/pt-br/cli-reference/github-deploys#squarecloud-app-deploy-webhook)
* SDKs: [`api.apps.deploys.setWebhook()`](/pt-br/sdks/js/deploys) (JavaScript), [`client.apps.deploys.set_webhook()`](/pt-br/sdks/py/deploys) (Python), [`c.Apps.Deploys.SetWebhook()`](/pt-br/sdks/go/deploys) (Go)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.