Webhooks

Um webhook publica mensagens em um canal de servidor sob nome e avatar próprios.

Rotas de gerenciamento utilizam um token de sessão de usuário ou token de bot. Todas as outras operações de webhook usam o ID do webhook e o token secreto em seu próprio caminho como credencial completa. Um cabeçalho Authorization enviado não concede acesso lá, e o Decoding Chat ainda o resolve, conforme descrito em Chaveamento de limite de taxa.

O recurso de Mensagens define os objetos de mensagem, entrada de rich embed e entrada de referência de mensagem.

Autorização

Uma operação de gerenciamento requer MANAGE_WEBHOOKS no nível do servidor e também no canal do webhook. MANAGE_WEBHOOKS é uma permissão elevada. Em um servidor cujo nível MFA seja elevado, um chamador que não seja o proprietário do servidor nem esteja cadastrado na autenticação multifator recebe 400 TWO_FACTOR_REQUIRED. O Decoding Chat confirma a permissão antes dessa verificação, portanto um chamador sem a permissão recebe 403 MISSING_PERMISSIONS.

O Decoding Chat resolve o servidor antes de cada operação de gerenciamento. Um servidor inexistente retorna 404 UNKNOWN_GUILD. Um chamador que não seja membro atual de um servidor existente recebe 403 MISSING_PERMISSIONS.

Listar webhooks do servidor, Listar webhooks do canal e Criar webhook nomeiam um servidor ou canal em seus caminhos, aplicando a verificação de disponibilidade. Um servidor com UNAVAILABLE_FOR_EVERYONE recusa uma requisição autenticada com 403 MISSING_ACCESS antes da execução. UNAVAILABLE_FOR_EVERYONE_BUT_STAFF faz o mesmo para uma conta sem o flag de staff da instância. As rotas de gerenciamento restantes nomeiam apenas um ID de webhook e não passam por essa restrição.

O Decoding Chat verifica o name de webhook enviado contra as listas de bloqueio de frases e URLs da instância; uma correspondência retorna 403 CONTENT_BLOCKED. As mesmas listas verificam o conteúdo e texto de embed resolvidos de uma mensagem criada ou editada, retornando o mesmo código em caso de correspondência. O membro avatar é isento dessa verificação, e o Decoding Chat valida seus bytes decodificados contra a lista de hashes de assets banidos ao armazená-los.

Chaveamento de limite de taxa

Cada bucket de rota nesta página é chaveado pela identidade do chamador e pelo parâmetro de caminho em seu nome de bucket. A identidade do chamador é a conta autenticada quando resolvida, e o endereço IP do cliente caso contrário, limitando operações por endereço quando autenticadas por token.

Quando uma requisição a uma operação autenticada por token envia um cabeçalho Authorization, o Decoding Chat lê essa credencial apenas para escolher a chave do limite de taxa. Limites de taxa define o chaveamento em detalhes.

O limite HTTP global aplica-se a todas as rotas de gerenciamento. Obter webhook com token, Atualizar webhook com token e Excluir webhook com token o consomem sob a identidade do chamador. Todas as outras rotas nesta página são isentas e limitadas apenas por seu próprio bucket de rota.

Recusa de origem

O Decoding Chat recusa chamadas do cliente web oficial em Executar webhook, Obter mensagem de webhook, Editar mensagem de webhook e Excluir mensagem de webhook. Uma requisição cujo cabeçalho Origin seja exatamente https://web.fluxer.app ou https://web.canary.fluxer.app retorna 403 INVALID_API_ORIGIN.

Requisições sem Origin, ou com qualquer outro valor, passam na verificação. Ela roda após o limite de taxa de rota e antes da validação do caminho.

/v1/webhooks/{webhook_id}/{token} e /v1/webhooks/{webhook_id}/{token}/messages/{message_id} possuem uma segunda política CORS permitindo qualquer origem, conforme detalhado no contrato de requisições cross-origin.

Objeto de webhook

Um webhook pertence a exatamente um servidor e envia mensagens para exatamente um canal de texto ou voz daquele servidor. O Decoding Chat gera seu token de execução uma vez na criação e nunca o rotaciona, tornando o par de ID e token uma credencial bearer durante a vida do webhook.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do webhook
guild_id	snowflake	O ID do servidor que contém o webhook
channel_id	snowflake	O ID do canal para onde o webhook envia mensagens
name	string	O nome sob o qual o webhook envia mensagens (1-80 caracteres)
avatar	?string	O hash do avatar sob o qual o webhook envia mensagens, ou null quando sem avatar
token1	string	O token secreto que autoriza a execução deste webhook
user2	usuário parcial object	A conta que criou o webhook

¹ 64 caracteres do alfabeto alfanumérico de 62 caracteres. Nenhuma operação o rotaciona ou reemite

² Ausente no objeto de webhook de token. O valor é o parcial de usuário excluído quando a conta criadora não existe mais

Exemplo

{
  "id": "1501314428688998182",
  "guild_id": "1501314428688990000",
  "channel_id": "1501314428688991111",
  "name": "Build bot",
  "avatar": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "token": "Xk3Qw9ZpL2vB7nR4tY6uI8oP0aS1dF5gH2jK4lZ9xC7vB1nM3qW5eR8tY0uI2oP4",
  "user": {
    "id": "1501314428688990001",
    "username": "ada",
    "discriminator": "0001",
    "avatar": null
  }
}

Objeto de webhook de token

Operações autenticadas por token retornam este objeto. Possui todos os campos do objeto de webhook, exceto user.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do webhook
guild_id	snowflake	O ID do servidor que contém o webhook
channel_id	snowflake	O ID do canal para onde o webhook envia mensagens
name	string	O nome sob o qual o webhook envia mensagens (1-80 caracteres)
avatar	?string	O hash do avatar sob o qual o webhook envia mensagens, ou null quando sem avatar
token	string	O token secreto que autoriza a execução deste webhook

O token é retornado por completo

Todas as operações que retornam um objeto de webhook ou um objeto de webhook de token incluem o token de execução completo, concedendo autoridade total de execução e gerenciamento sobre cada webhook nomeado.

Corpo de mensagem de webhook

Executar webhook aceita este corpo JSON. Todos os campos podem ser omitidos, e {} passa na validação do schema retornando 400 CANNOT_SEND_EMPTY_MESSAGE.

Estrutura

Campo	Tipo	Descrição
content?1	?string	Conteúdo da mensagem
embeds?2	array[entrada de rich embed object]	Rich embeds
attachments?3	array[entrada de anexo de webhook object]	Metadados de anexos
message_reference?4	?entrada de referência de mensagem object	Referência de resposta/encaminhamento, ou null
allowed_mentions?5	?menções permitidas object	Política de análise de menções, ou null
flags?	integer	Flags de mensagem, onde omissão é tratada como zero e bits fora da máscara enviável são limpos
favorite_meme_id?	?snowflake	Meme favorito a anexar
sticker_ids?	?array[snowflake]	No máximo 3 IDs de stickers
tts?6	boolean	Solicitação de conversão de texto em voz
nonce?7	string | integer	Identificador de mensagem do cliente (1-32 caracteres). Inteiro seguro torna-se string decimal
username?8	?string	Sobreposição de nome de webhook por mensagem (1-80 caracteres), ou null
avatar_url?8	?string	URL absoluta http/https de sobreposição de avatar por mensagem (máx. 2.048 caracteres), ou null

¹ Limitado ao maior valor entre max_message_length do servidor ou 4000 caracteres. Exceder retorna 400 INVALID_FORM_BODY com código CONTENT_EXCEEDS_MAX_LENGTH

² Limitado pelo valor max_embeds_per_message do servidor (padrão 10). Exceder retorna 400 INVALID_FORM_BODY com TOO_MANY_EMBEDS

³ Corpo JSON não anexa arquivos. Corpos multipart anexam arquivos como descrito em Executar webhook

⁴ Referência de encaminhamento requer channel_id e message_id, e não deve acompanhar conteúdo, embeds ou anexos. Ver referências de mensagem

⁵ Política omitida suprime todas as menções (oposto do padrão em Criar mensagem)

⁶ Não conta na verificação de mensagem não vazia (tts isolado retorna 400 CANNOT_SEND_EMPTY_MESSAGE). Mensagens de webhook nunca são marcadas como text-to-speech

⁷ Memorizado por webhook por 5 minutos e ecoado em Message Create. Reexecuções com o mesmo nonce retornam a primeira mensagem sem criar duplicata; reexecuções após mudança de canal retornam 404 UNKNOWN_MESSAGE

⁸ Aplica-se à mensagem criada; o webhook armazenado mantém nome e avatar próprios

Quando embeds está ausente, a chave singular embed é reescrita como array de um elemento, e embed null torna-se array vazio. Havendo ambos, embed é descartado.

Corpos multipart aceitam anexos pré-enviados e metadados de anexo multipart direto.

Objeto de entrada de anexo de webhook

Corpo JSON de mensagem de webhook aceita esta estrutura de metadados. Todos os membros são opcionais; membros fora da tabela são descartados.

Estrutura

Campo	Tipo	Descrição
id?	snowflake | integer	O ID do anexo
filename?	string	Nome do arquivo do anexo (1-1024 caracteres)
description?	string	Descrição do anexo (1-4096 caracteres)
content_type?	string	Tipo de mídia (1-256 caracteres)
size?	integer	Contagem de bytes como inteiro seguro não negativo
url?	string	URL absoluta http ou https (máx. 2.048 caracteres)
proxy_url?	string	URL absoluta http ou https (máx. 2.048 caracteres)
height?	integer	Altura em pixels
width?	integer	Largura em pixels
ephemeral?	boolean	Se o anexo é efêmero
duration?	number	Duração de áudio em segundos
waveform?	string	Dados de forma de onda Base64 (1-256 caracteres)
flags?	integer	Flags de anexo

Corpo JSON não anexa arquivos

A execução anexa apenas entradas com upload_filename, e este objeto não possui esse membro. Para anexar arquivos, use corpo multipart.

Entradas em corpos JSON são descartadas e não contam para limites de anexos nem verificação de mensagem não vazia.

Referências de mensagem

Execução de webhook aceita o objeto de entrada de referência de mensagem. Restrições específicas de webhooks:

O campo channel_id é obrigatório para encaminhamentos e deve ser igual ao canal do webhook. Outros canais retornam 404 UNKNOWN_MESSAGE. Referências de resposta resolvem no próprio canal do webhook e ignoram este campo.

A mensagem referenciada deve existir no canal do webhook (ausentes retornam 404 UNKNOWN_MESSAGE). Respostas exigem mensagens comuns ou de resposta (outros tipos retornam 400 INVALID_FORM_BODY com código CANNOT_REPLY_TO_SYSTEM_MESSAGE).

Encaminhamentos não podem acompanhar conteúdo, embeds ou anexos (caso contrário: 400 INVALID_FORM_BODY com FORWARD_MESSAGES_CANNOT_CONTAIN_CONTENT). Faltando channel_id ou message_id, retorna FORWARD_REFERENCE_REQUIRES_CHANNEL_AND_MESSAGE.

Corpo de edição de mensagem de webhook

Editar mensagem de webhook aceita este corpo JSON. Campos fornecidos substituem valores armazenados; omitidos os mantêm. Corpos sem content visível, embeds ou flags retornam 400 CANNOT_SEND_EMPTY_MESSAGE.

Estrutura

Campo	Tipo	Descrição
content?1	?string	Conteúdo de substituição, ou null
embeds?2	array[entrada de rich embed object]	Coleção de embeds substituta
flags?	integer	Flags de mensagem substitutos
allowed_mentions?	?menções permitidas object	Política de análise de menções substituta, ou null

¹ Aplica-se o mesmo tamanho máximo efetivo de Executar webhook

² O array substitui a coleção inteira (vazio remove todos os embeds). Aplica-se o teto max_embeds_per_message

flags substitui apenas bits da máscara enviável; outros bits armazenados são mantidos.

Objetos de callback do Slack

Objetos aceitos por Executar webhook do Slack e conversão para embeds.

Objeto de callback do Slack

Estrutura

Campo	Tipo	Descrição
text?1	string	Texto da mensagem
username?	string	Sobreposição de nome do webhook (1-80 caracteres)
icon_url?2	string	Sobreposição de URL do avatar do webhook
attachments?	array[anexo do Slack object]	Anexos do Slack convertidos para embeds

¹ Omitindo texto e convertendo ao menos um anexo, o conteúdo fica como string vazia

² Usado apenas se for URL absoluta http/https de até 2.048 caracteres; outros valores são descartados

Objeto de anexo do Slack

Estrutura

Campo	Tipo	Descrição
fallback?1	string	Texto alternativo
pretext?1	string	Texto acima do anexo
text?1	string	Texto principal do anexo
color?2	string	Cor da barra lateral
title?	string	Título do anexo (mapeado para título do embed)
title_link?3	string	URL do título (mapeado para URL do embed)
fields?4	array[campo de anexo do Slack object]	Campos mapeados para campos de embed
footer?	string	Texto do rodapé (mapeado para rodapé do embed)
ts?5	number	Segundos Unix (mapeado para timestamp do embed)
author_name?6	string	Nome do autor (mapeado para autor do embed)
author_link?3	string	URL do autor (mapeado para URL do autor do embed)
author_icon?3	string	URL do ícone do autor (mapeado para ícone do autor)
image_url?3	string	URL da imagem principal (mapeado para imagem do embed)
thumb_url?3	string	URL da miniatura (mapeado para miniatura do embed)

¹ Descrição do embed une pretext e text por quebra de linha; fallback é usado se ambos estiverem ausentes

² Mapeado para cor do embed apenas se for 6 dígitos hexadecimais (com # opcional)

³ Usado apenas se for URL absoluta http/https de até 2.048 caracteres

⁴ Convertido apenas se contiver título e valor

⁵ Aceito como número JSON ou string decimal (inteiro não negativo)

⁶ Autor do embed é emitido apenas com author_name

Objeto de campo de anexo do Slack

Estrutura

Campo	Tipo	Descrição
title?	string	Título do campo (mapeado para nome do campo)
value?	string	Valor do campo (mapeado para valor do campo)
short?	boolean	Se renderiza em linha (padrão false)

Campos do Slack não têm limite individual de tamanho

Valores do Slack não aplicam limites por título, descrição, rodapé ou campos de embed.

O schema do Slack limita apenas username (1-80 caracteres; outros retornam WEBHOOK_NAME_LENGTH_INVALID).

Conversões sem conteúdo ou embed retornam 400 CANNOT_SEND_EMPTY_MESSAGE. Conteúdo longo retorna CONTENT_EXCEEDS_MAX_LENGTH. Excesso de embeds retorna TOO_MANY_EMBEDS.

Objetos de callback do GitHub

Estruturas aceitas por Executar webhook do GitHub.

Objeto de callback do GitHub

Estrutura

Campo	Tipo	Descrição
action?1	?string	Ação do evento do GitHub, ou null
answer?	?comentário do GitHub object	Resposta de discussão aceita, ou null (validado, não renderizado)
check_run?	?execução de verificação do GitHub object	Dados de execução de verificação, ou null
check_suite?	?suíte de verificação do GitHub object	Dados de suíte de verificação, ou null
comment?	?comentário do GitHub object	Comentário de issue, review, commit ou discussão, ou null
commits?	?array[commit do GitHub object]	Commits de push, ou null
compare?	?string	URL de comparação absoluta, ou null
discussion?	?discussão do GitHub object	Dados de discussão, ou null
forced?	?boolean	Se o push foi forçado, ou null
forkee?	?serviço do GitHub object	Repositório de fork, ou null
head_commit?	?commit do GitHub object	Commit principal, ou null
issue?	?issue do GitHub object	Dados da issue, ou null
member?	?usuário do GitHub object	Dados de membro do repositório, ou null
pull_request?2	?issue do GitHub object	Representação de pull request, ou null
ref_type?3	?string	Tipo de referência Git, ou null
ref?	?string	Referência Git, ou null
release?	?release do GitHub object	Dados da release, ou null
repository?4	?serviço do GitHub object	Dados do repositório, ou null
review?	?review do GitHub object	Dados de review de pull request, ou null
sender	usuário do GitHub object	Remetente do evento

¹ Eventos com ações obrigatórias em Tipos de eventos do GitHub renderizam apenas quando action coincidir

² Pull requests usam a mesma representação de issues (apenas campos de issue do GitHub são consumidos)

³ Apenas branch e tag renderizam eventos de criação/exclusão

⁴ Eventos renderizados requerem repositório (ausência não renderiza mensagem)

pull_request no nível superior define o texto de issue_comment (pull request se presente, issue se ausente).

Strings aceitam até 152.133 caracteres. URLs devem ter até 2.048 caracteres (http/https). Valores malformados retornam 400 INVALID_FORM_BODY.

Títulos são truncados em 70 caracteres (exceto push comum, check run e check suite em 256). Descrições em 350 caracteres (exceto push forçado com link fixo). Entidades HTML são decodificadas antes do truncamento.

Objeto de usuário do GitHub

Estrutura

Campo	Tipo	Descrição
id	integer	ID de usuário do GitHub de 32 bits não negativo (validado, não renderizado)
login	string	Login do GitHub (autor do embed)
html_url	string	URL absoluta do perfil
avatar_url	string	URL absoluta do avatar

Objeto de serviço do GitHub

Estrutura

Campo	Tipo	Descrição
id	integer	ID do repositório no GitHub (validado, não renderizado)
html_url	string	URL absoluta do repositório
name1	string	Nome do repositório
full_name1	string	Nome qualificado do repositório (com proprietário)

¹ Push, check run e check suite usam name; outros usam full_name

Objeto de autor do GitHub

Estrutura

Campo	Tipo	Descrição
username?	?string	Nome de usuário no GitHub, ou null (validado, não renderizado)
name	string	Nome de exibição do autor (renderizado ao lado de commits)

Objeto de commit do GitHub

Estrutura

Campo	Tipo	Descrição
id1	string	Identificador do commit
url	string	URL absoluta da API do commit
message2	string	Mensagem do commit
author	autor do GitHub object	Autor do commit

¹ Reduzido para os primeiros 7 caracteres na renderização

² Frases This reverts commit <sha>. com SHA de 40 caracteres são reescritas como link Markdown para o commit revertido

Objeto de comentário do GitHub

Estrutura

Campo	Tipo	Descrição
id	string | integer (validado, não renderizado)	ID de comentário de 64 bits (decimal string ou inteiro seguro)
html_url	string	URL absoluta do comentário
user	usuário do GitHub object	Autor do comentário
commit_id?1	?string	Identificador do commit associado, ou null
body	string	Corpo do comentário

¹ Obrigatório para eventos commit_comment

Objeto de discussão do GitHub

Estrutura

Campo	Tipo	Descrição
title	string	Título da discussão
number	integer	Número da discussão (inteiro 32 bits não negativo)
html_url	string	URL absoluta da discussão
answer_html_url?	?string	URL absoluta da resposta aceita, ou null (validado, não renderizado)
body?	?string	Corpo da discussão, ou null
user	usuário do GitHub object	Autor da discussão

Objeto de issue do GitHub

Estrutura

Campo	Tipo	Descrição
id1	string | integer	ID da issue ou pull request de 64 bits
number	integer	Número da issue ou pull request
html_url	string	URL absoluta da issue ou pull request
user1	usuário do GitHub object	Autor da issue ou pull request
title	string	Título da issue ou pull request
body?2	?string	Corpo da issue ou pull request, ou null

¹ Aceito e validado, nunca renderizado. O autor do embed vem do remetente do callback ou do comentário

² Renderizado apenas para a ação opened

Objeto de release do GitHub

Estrutura

Campo	Tipo	Descrição
id	integer	ID da release (validado, não renderizado)
tag_name	string	Nome da tag Git
html_url	string	URL absoluta da release
body?	?string	Corpo da release, ou null (validado, não renderizado)

Objeto de review do GitHub

Estrutura

Campo	Tipo	Descrição
user	usuário do GitHub object	Autor da review
body?	?string	Corpo da review, ou null
html_url	string	URL absoluta da review
state1	string	Estado da review

¹ Validado, mas aprovações, alterações solicitadas e comentários renderizam o mesmo embed

Objeto de pull request de verificação do GitHub

Estrutura

Campo	Tipo	Descrição
number	integer	Número da pull request (validado, não renderizado)

Objeto de aplicação de verificação do GitHub

Estrutura

Campo	Tipo	Descrição
name	string	Nome da aplicação de verificação (renderizado no título do embed)

Objeto de suíte de verificação do GitHub

Estrutura

Campo	Tipo	Descrição
conclusion?1	?string	Conclusão da verificação, ou null
head_branch?	?string	Branch principal, ou null
head_sha	string	SHA do commit principal
pull_requests?	?array[pull request de verificação do GitHub object]	Pull requests associadas, ou null
app	aplicação de verificação do GitHub object	Aplicação de verificação

¹ skipped suprime a mensagem; success renderiza embed verde; outros renderizam vermelho

Objeto de saída de execução de verificação do GitHub

Estrutura

Campo	Tipo	Descrição
title?	?string	Título da saída, ou null
summary?	?string	Resumo da saída, ou null

Objeto de execução de verificação do GitHub

Estrutura

Campo	Tipo	Descrição
conclusion?1	?string	Conclusão da verificação, ou null
name	string	Nome da execução de verificação
html_url	string	URL absoluta da execução
check_suite2	suíte de verificação do GitHub object	Suíte de verificação pai
details_url?	?string	URL de detalhes, ou null
output?	?saída de execução de verificação do GitHub object	Saída da verificação, ou null
pull_requests?	?array[pull request de verificação do GitHub object]	Pull requests associadas, ou null

¹ success renderiza embed verde; outros renderizam vermelho

² Suíte pai com conclusão skipped não produz mensagem

Tipos de eventos do GitHub

Selecionados pelo cabeçalho X-GitHub-Event. Tipos não listados ou cabeçalhos ausentes são confirmados sem criar mensagem. Todos exigem repositório.

Valor	Descrição
commit_comment	Comentário em commit (requer ação created e commit_id)
create	Criação de branch ou tag (requer ref e ref_type)
delete	Exclusão de branch ou tag (requer ref e ref_type)
fork	Criação de fork (requer forkee)
issue_comment	Comentário em issue ou pull request (requer ação created, comment e issue)
issues	Ciclo de vida da issue (requer issue e ação opened, closed ou reopened)
member	Adição de colaborador (requer ação added e member)
public	Repositório tornado público
pull_request	Ciclo de vida do PR (requer pull_request e ação opened, closed ou reopened)
pull_request_review	Review de PR (requer ação submitted, review e pull_request)
pull_request_review_comment	Comentário de review (requer ação created, comment e pull_request)
push	Push Git (requer ref)
release	Publicação de release (requer ação published e release)
watch	Estrela no repositório (requer ação started)
check_run	Conclusão de verificação (requer ação completed e check_run)
check_suite	Conclusão de suíte (requer ação completed e check_suite)
discussion	Nova discussão (requer ação created e discussion)
discussion_comment	Comentário em discussão (requer ação created, comment e discussion)
repository	Criação de repositório (requer ação created)

Pushes comuns renderizam uma linha por commit.

Objetos de callback do Instatus

Estruturas aceitas por Executar webhook do Instatus.

Objeto de callback do Instatus

Estrutura

Campo	Tipo	Descrição
meta?	?metadados do Instatus object	Metadados do callback, ou null
page?1	?página do Instatus object	Dados da página de status, ou null
incident?2	?incidente do Instatus object	Dados do incidente, ou null
maintenance?2	?manutenção do Instatus object	Dados da manutenção, ou null
component_update?2	?atualização de componente do Instatus object	Transição de componente, ou null
component?2	?componente do Instatus object	Dados do componente, ou null

¹ Fornece rodapé e URL padrão do embed

² Selecionado na ordem: incidente, manutenção, transição de componente

Objeto de metadados do Instatus

Estrutura

Campo	Tipo	Descrição
unsubscribe?	?string	Valor de cancelamento de inscrição (máx. 2.048 caracteres), ou null
documentation?	?string	Valor de documentação (máx. 2.048 caracteres), ou null

Objeto de página do Instatus

Estrutura

Campo	Tipo	Descrição
id?	?string	ID da página (máx. 256 caracteres), ou null
status_indicator?	?string	Indicador de status (máx. 256 caracteres), ou null
status_description?	?string	Descrição de status (máx. 1.024 caracteres), ou null
url?	?string	URL da página (máx. 2.048 caracteres), ou null

Itens retroativos adicionam Backfilled ao rodapé.

Objeto de componente afetado do Instatus

Estrutura

Campo	Tipo	Descrição
id?	?string	ID do componente (máx. 256 caracteres), ou null
name?	?string	Nome do componente (máx. 1.024 caracteres), ou null
status?	?string	Status do componente (máx. 256 caracteres), ou null

Objeto de componente do Instatus

Estrutura

Campo	Tipo	Descrição
id?	?string	ID do componente (máx. 256 caracteres), ou null
name?1	?string	Nome do componente (máx. 1.024 caracteres), ou null
status?2	?string	Status do componente (máx. 256 caracteres), ou null
created_at?3	?string	Horário de criação (máx. 64 caracteres), ou null

¹ Sem nome renderiza A component

² Status padrão da transição se new_status estiver ausente

³ Horário padrão do embed se created_at estiver ausente

Objeto de atualização de incidente do Instatus

Estrutura

Campo	Tipo	Descrição
id?	?string	ID da atualização (máx. 256 caracteres), ou null
incident_id?	?string	ID do incidente (máx. 256 caracteres), ou null
markdown?1	?string	Corpo em Markdown (máx. 65.536 caracteres), ou null
status?	?string	Status da atualização (máx. 256 caracteres), ou null
created_at?1	?string	Horário de criação (máx. 64 caracteres), ou null
updated_at?	?string	Horário de atualização (máx. 64 caracteres), ou null

¹ A atualização com o created_at mais recente define o corpo do embed (truncado em 4.096 caracteres) e o timestamp

Objeto de incidente do Instatus

Estrutura

Campo	Tipo	Descrição
id?	?string	ID do incidente (máx. 256 caracteres), ou null
name?1	?string	Nome do incidente (máx. 1.024 caracteres), ou null
url?	?string	URL do incidente (máx. 2.048 caracteres), ou null
status?2	?string	Status do incidente (máx. 256 caracteres), ou null
backfilled?3	?boolean	Se foi retroativo, ou null
created_at?4	?string	Horário de criação (máx. 64 caracteres), ou null
updated_at?4	?string	Horário de atualização (máx. 64 caracteres), ou null
resolved_at?	?string	Horário de resolução (máx. 64 caracteres), ou null
incident_updates?	?array[atualização de incidente do Instatus object]	Atualizações de incidente, ou null
affected_components?	?array[componente afetado do Instatus object]	Componentes afetados, ou null

¹ Nome torna-se o título do embed (truncado em 256 caracteres)

² Define cor e campo Status através de Valores de status do Instatus

³ true adiciona Backfilled ao rodapé

⁴ Timestamp do embed usa o primeiro horário válido em: created_at da última atualização, updated_at do objeto, created_at do objeto

Objeto de atualização de manutenção do Instatus

Estrutura

Campo	Tipo	Descrição
id?	?string	ID da atualização (máx. 256 caracteres), ou null
maintenance_id?	?string	ID da manutenção (máx. 256 caracteres), ou null
markdown?1	?string	Corpo em Markdown (máx. 65.536 caracteres), ou null
created_at?1	?string	Horário de criação (máx. 64 caracteres), ou null
updated_at?	?string	Horário de atualização (máx. 64 caracteres), ou null

¹ A atualização mais recente define descrição (truncada em 4.096 caracteres) e timestamp

Objeto de manutenção do Instatus

Estrutura

Campo	Tipo	Descrição
id?	?string	ID da manutenção (máx. 256 caracteres), ou null
name?1	?string	Nome da manutenção (máx. 1.024 caracteres), ou null
url?	?string	URL da manutenção (máx. 2.048 caracteres), ou null
status?2	?string	Status da manutenção (máx. 256 caracteres), ou null
maintenance_start_date?3	?string	Horário de início (máx. 64 caracteres), ou null
maintenance_end_date?3	?string	Horário de término (máx. 64 caracteres), ou null
backfilled?	?boolean	Se foi retroativo, ou null
created_at?4	?string	Horário de criação (máx. 64 caracteres), ou null
updated_at?4	?string	Horário de atualização (máx. 64 caracteres), ou null
resolved_at?	?string	Horário de resolução (máx. 64 caracteres), ou null
maintenance_updates?	?array[atualização de manutenção do Instatus object]	Atualizações de manutenção, ou null
affected_components?	?array[componente afetado do Instatus object]	Componentes afetados, ou null

¹ Nome torna-se título (truncado em 256 caracteres)

² Ausente renderiza a cor de manutenção

³ Renderizados como timestamp completo no campo Window

⁴ Timestamp usa o primeiro valor válido entre a última atualização, updated_at e created_at

Objeto de atualização de componente do Instatus

Estrutura

Campo	Tipo	Descrição
created_at?	?string	Horário de criação (máx. 64 caracteres), ou null
new_status?1	?string	Novo status do componente (máx. 256 caracteres), ou null
component_id?	?string	ID do componente (máx. 256 caracteres), ou null

¹ Prefere new_status, depois o status do componente, usando updated caso contrário

Valores de status do Instatus

O Decoding Chat converte para maiúsculas e remove caracteres fora de A-Z.

Valor	Descrição
UP	Renderizado como All systems operational, cor neutra
HASISSUES	Renderizado como Has issues, cor neutra
OPERATIONAL	Renderizado como Operational, cor de operacional
UNDERMAINTENANCE	Renderizado como Under maintenance, cor de manutenção
DEGRADEDPERFORMANCE	Renderizado como Degraded performance, cor de degradação
PARTIALOUTAGE	Renderizado como Partial outage, cor de queda parcial
MAJOROUTAGE	Renderizado como Major outage, cor de queda total
INVESTIGATING	Renderizado como Investigating, cor de queda total
IDENTIFIED	Renderizado como Identified, cor de queda parcial
MONITORING	Renderizado como Monitoring, cor de degradação
RESOLVED	Renderizado como Resolved, cor de operacional
NOTSTARTEDYET	Renderizado como Scheduled, cor de manutenção
PLANNED	Renderizado como Planned, cor de manutenção
INPROGRESS	Renderizado como In progress, cor de manutenção
COMPLETED	Renderizado como Completed, cor de operacional

Listar webhooks do servidor

GET/v1/guilds/{guild_id}/webhooksBot

Retorna array de objetos de webhook em um servidor. Requer permissão MANAGE_WEBHOOKS no nível do servidor.

Parâmetros de caminho

Campo	Tipo	Descrição
guild_id	snowflake	O ID do servidor cujos webhooks são retornados

Resposta

Status	Corpo	Condição
200	array[webhook object]	Webhooks foram retornados (array vazio se não houver)
400	resposta de erro	Snowflake inválido
400	resposta de erro	Sem autenticador em servidor com MFA elevado (TWO_FACTOR_REQUIRED)
403	resposta de erro	Credencial bearer (ACCESS_DENIED), ação pendente (ACCOUNT_SUSPICIOUS_ACTIVITY), servidor indisponível (MISSING_ACCESS), ou sem permissão (MISSING_PERMISSIONS)
404	resposta de erro	Servidor não existe (UNKNOWN_GUILD)

Um webhook é retornado apenas se o chamador possuir VIEW_CHANNEL e MANAGE_WEBHOOKS em seu canal.

Rate limit

40 requisições por 10 segundos para cada usuário autenticado e ID de servidor, no bucket webhook:list::guild_id.

Listar webhooks do canal

GET/v1/channels/{channel_id}/webhooksBot

Retorna array de objetos de webhook em canal de texto/voz de servidor. Requer MANAGE_WEBHOOKS no servidor e no canal.

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal de texto ou voz do servidor

Resposta

Status	Corpo	Condição
200	array[webhook object]	Webhooks foram retornados (array vazio se não houver)
400	resposta de erro	Snowflake inválido
400	resposta de erro	Sem autenticador em servidor com MFA elevado (TWO_FACTOR_REQUIRED)
403	resposta de erro	Credencial bearer, ação pendente, servidor indisponível, sem acesso ao canal, sem permissão ou falta verificação de idade
404	resposta de erro	Canal (UNKNOWN_CHANNEL) ou servidor (UNKNOWN_GUILD) não existe

Rate limit

40 requisições por 10 segundos para cada usuário autenticado e ID de canal, no bucket webhook:list::channel_id.

Criar webhook

POST/v1/channels/{channel_id}/webhooksBotAudit reason

Cria um webhook em canal de texto/voz de servidor e retorna o webhook com seu token de execução. Requer MANAGE_WEBHOOKS no servidor e canal. Aceita motivo de auditoria. Emite Webhooks Update.

Limites: max_webhooks_per_guild (padrão 1000) e max_webhooks_per_channel (padrão 15).

Parâmetros de caminho

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal de texto ou voz do servidor

Corpo JSON

Campo	Tipo	Descrição
name	string	Nome do webhook (1-80 caracteres)
avatar?	?base64 string	Imagem de avatar codificada em Base64, ou null

O avatar deve ter no máximo 10 MiB (avatar_max_size). AVIF animado é rejeitado.

Resposta

Status	Corpo	Condição
200	webhook object	O webhook foi criado
400	resposta de erro	Corpo/avatar inválido, limite de webhooks do servidor/canal atingido (MAX_WEBHOOKS_PER_GUILD/MAX_WEBHOOKS_PER_CHANNEL) ou sem autenticador (TWO_FACTOR_REQUIRED)
403	resposta de erro	Credencial bearer, ação pendente, nome/avatar bloqueado (CONTENT_BLOCKED), servidor indisponível, sem permissão ou falta verificação de idade
404	resposta de erro	Canal (UNKNOWN_CHANNEL) ou servidor (UNKNOWN_GUILD) não existe

Efeitos colaterais

Grava entrada WEBHOOK_CREATE no log de auditoria. Emite Webhooks Update para sessões do servidor que veem o canal.

Rate limit

10 requisições por minuto para cada usuário autenticado e ID de canal, no bucket webhook:create::channel_id.

Obter webhook

GET/v1/webhooks/{webhook_id}Bot

Retorna um objeto de webhook. Requer ser membro do servidor e possuir MANAGE_WEBHOOKS no servidor e canal do webhook.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook a retornar

Resposta

Status	Corpo	Condição
200	webhook object	O webhook foi retornado
400	resposta de erro	Snowflake inválido ou sem autenticador em MFA elevado
403	resposta de erro	Credencial bearer, ação pendente ou falta de permissão
404	resposta de erro	Webhook (UNKNOWN_WEBHOOK) ou servidor (UNKNOWN_GUILD) não existe

Rate limit

100 requisições por 10 segundos para cada usuário autenticado e ID de webhook, no bucket webhook:read::webhook_id.

Atualizar webhook

PATCH/v1/webhooks/{webhook_id}BotAudit reason

Atualiza um webhook e retorna o objeto de webhook modificado. Emite Webhooks Update.

Limitações

• Requer MANAGE_WEBHOOKS no servidor e nos canais de origem e destino (caso movido).
• Aceita motivo de auditoria.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook a atualizar

Corpo JSON

Campo	Tipo	Descrição
name?	string	Nome de substituição (1-80 caracteres)
avatar?	?base64 string	Avatar de substituição em Base64, ou null para remover
channel_id?	snowflake	Canal de texto/voz de destino no mesmo servidor

Mover notifica apenas o canal de origem

É emitido um Dispatch com o canal de origem anterior. Clientes rastreando o canal de destino devem atualizá-lo manualmente.

Resposta

Status	Corpo	Condição
200	webhook object	O webhook foi atualizado
400	resposta de erro	Corpo/avatar inválido, canal de destino cheio (MAX_WEBHOOKS_PER_CHANNEL) ou sem autenticador (TWO_FACTOR_REQUIRED)
403	resposta de erro	Credencial bearer, ação pendente, nome/avatar bloqueado (CONTENT_BLOCKED), sem permissão ou falta verificação de idade
404	resposta de erro	Webhook (UNKNOWN_WEBHOOK), canal de destino (UNKNOWN_CHANNEL) ou servidor (UNKNOWN_GUILD) não existe

Efeitos colaterais

Grava entrada WEBHOOK_UPDATE no log de auditoria. Emite Webhooks Update.

Rate limit

20 requisições por 10 segundos para cada usuário autenticado e ID de webhook, no bucket webhook:update::webhook_id.

Excluir webhook

DELETE/v1/webhooks/{webhook_id}BotAudit reason

Exclui permanentemente um webhook e retorna 204 com corpo vazio. Requer MANAGE_WEBHOOKS no servidor e canal. Aceita motivo de auditoria. Emite Webhooks Update.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook a excluir

Exclusão remove o webhook e seu token permanentemente

Nenhuma operação restaura o webhook ou reemite seu token. Mensagens já criadas por ele permanecem no canal.

Resposta

Status	Corpo	Condição
204	vazio	O webhook foi excluído
400	resposta de erro	Snowflake inválido ou sem autenticador (TWO_FACTOR_REQUIRED)
403	resposta de erro	Credencial bearer, ação pendente ou falta de permissão
404	resposta de erro	Webhook (UNKNOWN_WEBHOOK) ou servidor (UNKNOWN_GUILD) não existe

Efeitos colaterais

Grava entrada WEBHOOK_DELETE no log de auditoria. Emite Webhooks Update.

Rate limit

20 requisições por 10 segundos para cada usuário autenticado e ID de webhook, no bucket webhook:delete::webhook_id.

Rotas com token

As rotas abaixo usam o ID do webhook e o token como credencial completa no caminho, dispensando o cabeçalho Authorization.

Obter webhook com token

GET/v1/webhooks/{webhook_id}/{token}

Retorna um objeto de webhook de token. Permissões não são avaliadas.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook a retornar
token	string	Token de execução do webhook (1-256 caracteres)

Resposta

Status	Corpo	Condição
200	webhook de token object	O webhook foi retornado
404	resposta de erro	Par de webhook e token não existe (UNKNOWN_WEBHOOK)

Rate limit

100 requisições por 10 segundos por identidade do chamador e ID de webhook, no bucket webhook:read::webhook_id.

Atualizar webhook com token

PATCH/v1/webhooks/{webhook_id}/{token}

Atualiza um webhook e retorna o objeto de webhook de token modificado. Não permite mover o webhook nem aceita motivo de auditoria. Emite Webhooks Update.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook a atualizar
token	string	Token de execução do webhook (1-256 caracteres)

Corpo JSON

Campo	Tipo	Descrição
name?	string	Nome de substituição (1-80 caracteres)
avatar?	?base64 string	Avatar de substituição em Base64, ou null para remover

O corpo é estrito

Campos desconhecidos (ex: channel_id) retornam 400.

Resposta

Status	Corpo	Condição
200	webhook de token object	O webhook foi atualizado
400	resposta de erro	Caminho, corpo, avatar ou campo desconhecido inválido
403	resposta de erro	Nome ou avatar bloqueado (CONTENT_BLOCKED)
404	resposta de erro	Par de webhook e token não existe (UNKNOWN_WEBHOOK)

Rate limit

20 requisições por 10 segundos por identidade e ID de webhook, no bucket webhook:update::webhook_id.

Excluir webhook com token

DELETE/v1/webhooks/{webhook_id}/{token}

Exclui permanentemente um webhook e retorna 204 com corpo vazio. Não aceita motivo de auditoria. Emite Webhooks Update.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook a excluir
token	string	Token de execução do webhook (1-256 caracteres)

Resposta

Status	Corpo	Condição
204	vazio	O webhook foi excluído
404	resposta de erro	Par de webhook e token não existe (UNKNOWN_WEBHOOK)

Rate limit

20 requisições por 10 segundos por identidade e ID de webhook, no bucket webhook:delete::webhook_id.

Executar webhook

POST/v1/webhooks/{webhook_id}/{token}

Cria uma mensagem de autoria do webhook. Com wait=true, retorna a mensagem criada; caso contrário, retorna 204 com corpo vazio. Recusa chamadas do cliente web oficial (ver recusa de origem). Emite Message Create.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook a executar
token	string	Token de execução do webhook (1-256 caracteres)

Parâmetros de consulta

Campo	Tipo	Descrição
wait?	boolean	Se deve retornar a mensagem criada (padrão false)

Corpo JSON

Corpo JSON de mensagem de webhook. Corpos sem Content-Type: multipart/form-data são lidos como JSON.

Corpo multipart

Campo	Tipo	Descrição
payload_json?	string	JSON de mensagem de webhook
files[n]?	binary	Anexo direto no índice baseado em zero n
content?	string	Conteúdo da mensagem (sobrepõe payload)
nonce?	string	Identificador do cliente (sobrepõe payload)
tts?	string	Solicitação text-to-speech (sobrepõe payload)
flags?	string	Flags de mensagem (sobrepõe payload)

Execuções multipart enviam arquivos como a conta criadora do webhook. Exige permissões VIEW_CHANNEL, SEND_MESSAGES e ATTACH_FILES.

Resposta

Status	Corpo	Condição
200	mensagem object	Mensagem criada e wait=true
204	vazio	Mensagem criada e wait=false (ou omitido)
400	resposta de erro	Entrada inválida, mensagem vazia, conteúdo longo ou excesso de anexos/embeds
403	resposta de erro	Origem do cliente web oficial (INVALID_API_ORIGIN) ou conteúdo bloqueado (CONTENT_BLOCKED)
404	resposta de erro	Webhook/token (UNKNOWN_WEBHOOK), canal (UNKNOWN_CHANNEL) ou mensagem referenciada (UNKNOWN_MESSAGE) não existe

Rate limit

60 requisições por minuto por identidade e ID de webhook, no bucket webhook:execute::webhook_id (isento do limite global).

Obter mensagem de webhook

GET/v1/webhooks/{webhook_id}/{token}/messages/{message_id}

Retorna uma mensagem criada pelo webhook. Recusa o cliente web oficial.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook autor da mensagem
token	string	Token de execução do webhook (1-256 caracteres)
message_id	snowflake	O ID da mensagem a retornar

Resposta

Status	Corpo	Condição
200	mensagem object	Mensagem do webhook foi retornada
403	resposta de erro	Origem do cliente web oficial (INVALID_API_ORIGIN) ou mensagem de outro autor (MISSING_PERMISSIONS)
404	resposta de erro	Webhook/token (UNKNOWN_WEBHOOK), canal (UNKNOWN_CHANNEL) ou mensagem (UNKNOWN_MESSAGE) não existe

Rate limit

60 requisições por minuto por identidade e ID de webhook, no bucket webhook:message_get::webhook_id.

Editar mensagem de webhook

PATCH/v1/webhooks/{webhook_id}/{token}/messages/{message_id}

Atualiza uma mensagem criada pelo webhook e retorna a mensagem modificada. Recusa o cliente web oficial. Emite Message Update.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook autor da mensagem
token	string	Token de execução do webhook (1-256 caracteres)
message_id	snowflake	O ID da mensagem a atualizar

Corpo JSON

Corpo de edição de mensagem de webhook. Apenas mensagens DEFAULT e REPLY são editáveis.

Resposta

Status	Corpo	Condição
200	mensagem object	Mensagem do webhook foi atualizada
400	resposta de erro	Entrada inválida, mensagem vazia, conteúdo/embeds em excesso ou tipo não editável
403	resposta de erro	Origem do cliente web (INVALID_API_ORIGIN), mensagem de outro autor (MISSING_PERMISSIONS) ou conteúdo bloqueado (CONTENT_BLOCKED)
404	resposta de erro	Webhook/token (UNKNOWN_WEBHOOK) ou mensagem (UNKNOWN_MESSAGE) não existe

Rate limit

30 requisições por minuto por identidade e ID de webhook, no bucket webhook:message_edit::webhook_id.

Excluir mensagem de webhook

DELETE/v1/webhooks/{webhook_id}/{token}/messages/{message_id}

Exclui uma mensagem criada pelo webhook e retorna 204 com corpo vazio. Recusa o cliente web oficial. Emite Message Delete.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook autor da mensagem
token	string	Token de execução do webhook (1-256 caracteres)
message_id	snowflake	O ID da mensagem a excluir

Resposta

Status	Corpo	Condição
204	vazio	A mensagem do webhook foi excluída
400	resposta de erro	Parâmetros de caminho inválidos ou canal não é mais de servidor (CANNOT_EXECUTE_ON_DM)
403	resposta de erro	Origem do cliente web (INVALID_API_ORIGIN) ou mensagem de outro autor (MISSING_PERMISSIONS)
404	resposta de erro	Webhook/token (UNKNOWN_WEBHOOK) ou mensagem (UNKNOWN_MESSAGE) não existe

Rate limit

30 requisições por minuto por identidade e ID de webhook, no bucket webhook:message_delete::webhook_id.

Executar webhook do GitHub

POST/v1/webhooks/{webhook_id}/{token}/github

Aceita callback do GitHub e cria uma mensagem formatada se o evento renderizar. Retorna sempre 204 com corpo vazio. Emite Message Create.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook a executar
token	string	Token de execução do webhook (1-256 caracteres)

Cabeçalhos da requisição

Campo	Tipo	Descrição
X-GitHub-Event?	string	Tipo de evento do GitHub
X-GitHub-Delivery?	string	Identificador de entrega usado para desduplicação

Corpo JSON

Objeto de callback do GitHub.

Resposta

Status	Corpo	Condição
204	vazio	Callback aceito, não renderizável ou duplicado no intervalo de 24h
403	resposta de erro	Texto de embed renderizado bloqueado (CONTENT_BLOCKED)
404	resposta de erro	Webhook/token (UNKNOWN_WEBHOOK) ou canal (UNKNOWN_CHANNEL) não existe

Rate limit

200 requisições por minuto por identidade e ID de webhook, no bucket webhook:github::webhook_id.

Executar webhook do Slack

POST/v1/webhooks/{webhook_id}/{token}/slack

Aceita callback compatível com o Slack, converte para conteúdo e embeds do Decoding Chat e cria uma mensagem. Emite Message Create.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook a executar
token	string	Token de execução do webhook (1-256 caracteres)

Corpo JSON

Objeto de callback do Slack.

Resposta

Status	Corpo	Condição
200	a string literal ok	Mensagem do callback foi criada
400	resposta de erro	Entrada inválida, conversão sem conteúdo/embed, conteúdo longo ou excesso de embeds
403	resposta de erro	Conteúdo ou embed convertido bloqueado (CONTENT_BLOCKED)
404	resposta de erro	Webhook/token (UNKNOWN_WEBHOOK) ou canal (UNKNOWN_CHANNEL) não existe

Callback do Slack responde em HTML

Corpo de sucesso é a string literal ok com Content-Type: text/html.

Rate limit

60 requisições por minuto por identidade e ID de webhook, no bucket webhook:execute::webhook_id.

Executar webhook do Instatus

POST/v1/webhooks/{webhook_id}/{token}/instatus

Aceita callback do Instatus e cria uma mensagem formatada se o callback renderizar. Retorna sempre 204 com corpo vazio. Emite Message Create.

Parâmetros de caminho

Campo	Tipo	Descrição
webhook_id	snowflake	O ID do webhook a executar
token	string	Token de execução do webhook (1-256 caracteres)

Corpo JSON

Objeto de callback do Instatus.

Resposta

Status	Corpo	Condição
204	vazio	Callback aceito, não renderizável ou duplicado no intervalo de 24h
403	resposta de erro	Texto de embed renderizado bloqueado (CONTENT_BLOCKED)
404	resposta de erro	Webhook/token (UNKNOWN_WEBHOOK) ou canal (UNKNOWN_CHANNEL) não existe

Rate limit

200 requisições por minuto por identidade e ID de webhook, no bucket webhook:instatus::webhook_id.