Webhooks

Os webhooks permitem que você receba notificações em tempo real quando ocorrem eventos na sua conta LabelGrid. Use webhooks para automatizar fluxos de trabalho e integrar com sistemas externos.

Para desenvolvedores: você também pode gerenciar webhooks de forma programática pela API. Consulte a documentação da API do LabelGrid para ver endpoints e exemplos.

Como os webhooks funcionam

Você configura um webhook - Informe uma URL e quais eventos quer monitorar
Um evento ocorre - Por exemplo, um lançamento é entregue a uma loja
O LabelGrid envia uma requisição POST - Seu servidor recebe os dados do evento
Seu sistema processa - Automatize fluxos de trabalho com base no evento

Como acessar os webhooks

Clique no ícone do seu perfil no canto superior direito
Selecione Webhooks no menu suspenso

Como criar um webhook

Clique em Create Webhook
Informe um Name para identificar este webhook
Informe a URL onde você quer receber as notificações
Selecione quais Events devem acionar este webhook
Clique em Create

Chave secreta do webhook

Ao criar um webhook, você recebe uma chave secreta. Use-a para verificar que as requisições recebidas realmente vêm do LabelGrid:

Guarde a chave secreta em local seguro
Verifique a assinatura nas requisições recebidas
Se ela for comprometida, gere uma nova chave secreta

Eventos disponíveis

Configure seu webhook para monitorar estes eventos. O identificador do evento é o valor que você verá na propriedade event do payload e no cabeçalho X-Webhook-Event:

Identificador do evento	Descrição
`delivery.completed`	Disparado quando um lançamento é entregue com sucesso a uma loja
`delivery.failed`	Disparado quando a entrega a uma loja falha
`takedown.completed`	Disparado quando uma solicitação de remoção (takedown) é concluída
`release.review.status_changed`	Disparado quando o status de revisão de um lançamento muda
`release.preflight.report_ready`	Disparado quando o relatório de Preflight QC de um lançamento em espera está pronto para ser obtido
`stream_radar.flag_created`	Disparado quando uma sinalização do Stream Radar é gerada, ou quando uma sinalização resolvida é reaberta em uma nova detecção
`stream_radar.flag_resolved`	Disparado quando uma sinalização do Stream Radar é resolvida porque as detecções cessaram
`release.distributed`	Disparado quando um lançamento é distribuído
`payment.statement_ready`	Disparado quando um extrato de pagamento está pronto para visualização
`transcode.completed`	Disparado quando a transcodificação de áudio de uma faixa é concluída com sucesso
`transcode.failed`	Disparado quando a transcodificação de uma faixa falha ou termina incompleta
`distribution.outlet.status_changed`	Disparado a cada transição de status de distribuição por loja

Você pode selecionar vários eventos em um único webhook ou criar webhooks separados para tipos de evento diferentes.

Você também pode ler essa lista de forma programática: GET /api/public/webhooks/event-types retorna todos os eventos junto com um esquema data que descreve as chaves e os tipos do seu payload, para que consumidores com esquema rígido possam ampliar antecipadamente a sua validação de entrada.

Como gerenciar webhooks

Visualizar seus webhooks

A lista de webhooks mostra:

Coluna	Descrição
Name	O nome que você atribuiu ao webhook
URL	Para onde as notificações são enviadas
Events	Número de eventos configurados
Status	Ativo ou Inativo
Success / Fail	Contagem de entregas bem-sucedidas e com falha
Last Triggered	Quando o webhook foi acionado pela última vez

Editar um webhook

Clique na ação Edit na linha do webhook
Altere o nome, a URL ou os eventos
Clique em Save

Ativar / desativar

Alterne o status de ativação de um webhook sem excluí-lo:

Active - O webhook receberá notificações
Inactive - O webhook está pausado; nenhuma notificação é enviada

Excluir um webhook

Clique na ação Delete na linha do webhook
Confirme a exclusão

Como testar webhooks

Antes de depender de um webhook em produção, teste-o:

Clique na ação Test no seu webhook
O LabelGrid envia um payload de teste para a sua URL
Verifique se o seu endpoint recebeu e processou tudo corretamente

Como visualizar os logs do webhook

Monitore a atividade do webhook e investigue problemas:

Clique na ação View Logs em um webhook
Veja o histórico de todas as entregas do webhook

Detalhes do log

Cada entrada do log mostra:

Campo	Descrição
Event Type	Qual evento acionou esta entrega
Response Status	Código de status HTTP retornado pelo seu servidor
Duration	Quanto tempo a requisição levou
Attempt	Número da tentativa de reenvio
Timestamp	Quando a entrega ocorreu

Formato do payload do webhook

Quando um evento ocorre, o LabelGrid envia uma requisição POST para a sua URL com um payload JSON:

{
  "event": "delivery.completed",
  "timestamp": "2026-05-05T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    // Dados específicos do evento
  }
}

O campo timestamp usa o formato ISO 8601. webhook_id é o ID do webhook que você configurou (corresponde ao cabeçalho X-Webhook-Id).

Payloads de evento

A estrutura do objeto data depende do tipo de event. Todos os tipos de campo abaixo são tipos JSON, conforme serializados no payload.

`delivery.completed`

Disparado uma vez por loja quando a entrega de um lançamento atinge um estado final de sucesso.

{
  "event": "delivery.completed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "complete"
  }
}

Campo	Tipo	Descrição
`distro_queue_id`	integer	ID interno da fila para esta tentativa de entrega
`release_id`	integer	O lançamento que foi entregue
`label_id`	integer	O selo dono do lançamento, para você rotear o evento sem uma consulta adicional
`release_cat`	string \| null	A referência de catálogo do seu lançamento
`outlet_id`	integer \| null	O ID da loja de destino
`outlet_name`	string \| null	Nome legível da loja (ex.: `"Spotify"`)
`status`	string	Sempre `"complete"` para este evento

`delivery.failed`

Disparado uma vez por loja quando a entrega de um lançamento atinge um estado final de falha. Mesmo payload de delivery.completed, acrescido do campo message.

{
  "event": "delivery.failed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "error",
    "message": "Outlet rejected the delivery: missing ISRC."
  }
}

Campo	Tipo	Descrição
`status`	string	Um de `error`, `fault`, `rejected`, `batch_exception`
`message`	string \| null	Motivo da falha informado pela loja ou pelo pipeline de distribuição

`takedown.completed`

Disparado uma vez por loja quando uma solicitação de remoção (takedown) é concluída com sucesso. Mesmo formato de delivery.completed, acrescido de um sinalizador takedown: true.

{
  "event": "takedown.completed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "status": "complete",
    "takedown": true
  }
}

`release.distributed`

Disparado uma vez por lançamento quando o lançamento passa para o estado de entrega distributed. Dispara apenas na transição para distributed, e não nas gravações seguintes enquanto o lançamento já está distribuído.

{
  "event": "release.distributed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "delivery_status": "distributed"
  }
}

`release.review.status_changed`

Disparado sempre que um lançamento muda de um estado de revisão para outro.

{
  "event": "release.review.status_changed",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "previous_status": "to_review",
    "new_status": "approved"
  }
}

Campo	Tipo	Descrição
`previous_status`	string	Status anterior. Um de `draft`, `to_review`, `approved`, `rejected`, `require_changes`, `audit`
`new_status`	string	Novo status. Mesmo conjunto de valores
`review_issues`	array (opcional)	Presente apenas nas transições para `require_changes` e `rejected`: os problemas que precisam da sua atenção. A chave é omitida em todas as outras transições, então não a trate como sempre presente

`release.preflight.report_ready`

Disparado quando o relatório de qualidade do Preflight QC de um lançamento em espera antes da revisão está pronto para ser obtido. Requer o complemento Preflight QC na sua conta.

{
  "event": "release.preflight.report_ready",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "release_title": "Summer EP",
    "generated_at": "2026-07-07T09:58:12+00:00",
    "profile": { "name": "quality_report", "version": 2 },
    "counts": { "blocking": 1, "informational": 2, "requires_feedback": 1 }
  }
}

Campo	Tipo	Descrição
`release_id`	integer	O lançamento ao qual o relatório pertence
`label_id`	integer	O selo dono do lançamento
`release_cat`	string \| null	A referência de catálogo do seu lançamento
`release_title`	string \| null	O título do lançamento
`generated_at`	string	Quando as verificações foram concluídas (ISO 8601). Corresponde ao `report.generated_at` do endpoint de relatório de qualidade
`profile`	object	O perfil de qualidade pelo qual as contagens foram calculadas: `{name, version}`
`counts`	object	Apenas contagens agregadas: `{blocking, informational, requires_feedback}`. A contagem `requires_feedback` se sobrepõe às outras duas

`stream_radar.flag_created`

Disparado quando uma sinalização do Stream Radar é gerada — seja uma sinalização totalmente nova, seja uma sinalização anteriormente resolvida sendo reaberta em uma nova detecção. Requer o complemento Stream Radar na sua conta. O campo transition distingue os dois casos: published para uma sinalização nova, reopened para uma que voltou a ficar ativa.

{
  "event": "stream_radar.flag_created",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "flag_id": 4501,
    "dsp": "spotify",
    "isrc": "USRC12345678",
    "release_id": 789,
    "track_id": 654,
    "severity": "high",
    "status": "active",
    "transition": "published",
    "first_detected_at": "2026-07-06T00:00:00+00:00",
    "last_detected_at": "2026-07-07T00:00:00+00:00",
    "estimated_affected_streams": 12500,
    "published_at": "2026-07-07T09:58:12+00:00",
    "resolved_at": null
  }
}

Campo	Tipo	Descrição
`flag_id`	integer	O identificador estável da sinalização; corresponde ao `id` nos endpoints do Stream Radar
`dsp`	string	A plataforma em que o padrão foi observado (ex.: `spotify`)
`isrc`	string	O ISRC da gravação envolvida
`release_id`	integer	O lançamento ao qual a gravação pertence
`track_id`	integer \| null	A faixa específica, quando o ISRC corresponde de forma inequívoca a uma das suas faixas
`severity`	string	`low`, `medium` ou `high`
`status`	string	`active` para este evento
`transition`	string	`published` para uma sinalização nova, `reopened` quando uma sinalização resolvida voltou a ficar ativa
`first_detected_at`	string \| null	Quando o padrão foi observado pela primeira vez para esta faixa e plataforma (ISO 8601)
`last_detected_at`	string \| null	A detecção mais recente (ISO 8601)
`estimated_affected_streams`	integer \| null	Uma estimativa de quantas reproduções estão envolvidas
`published_at`	string	Quando a sinalização foi gerada para você pela primeira vez (ISO 8601)
`resolved_at`	string \| null	`null` enquanto a sinalização está ativa

`stream_radar.flag_resolved`

Disparado quando uma sinalização do Stream Radar é resolvida porque as detecções cessaram. Requer o complemento Stream Radar. Mesmos campos de stream_radar.flag_created (sem o transition), com status definido como resolved e resolved_at preenchido.

{
  "event": "stream_radar.flag_resolved",
  "timestamp": "2026-07-14T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "flag_id": 4501,
    "dsp": "spotify",
    "isrc": "USRC12345678",
    "release_id": 789,
    "track_id": 654,
    "severity": "high",
    "status": "resolved",
    "first_detected_at": "2026-07-06T00:00:00+00:00",
    "last_detected_at": "2026-07-12T00:00:00+00:00",
    "estimated_affected_streams": 18700,
    "published_at": "2026-07-07T09:58:12+00:00",
    "resolved_at": "2026-07-14T09:55:03+00:00"
  }
}

`payment.statement_ready`

Disparado quando um extrato de pagamento é gerado e fica pronto para visualização.

{
  "event": "payment.statement_ready",
  "timestamp": "2026-05-18T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "payment_request_id": 1024,
    "invoice_number": "INV-2026-001",
    "period": "2026-04-30",
    "amount": 1234.56,
    "total_due_usd": 1234.56,
    "currency": "USD"
  }
}

Campo	Tipo	Descrição
`payment_request_id`	integer	ID interno da solicitação de pagamento
`invoice_number`	string	Referência da fatura do extrato
`period`	string \| null	Data de fim do período (data ISO 8601, `YYYY-MM-DD`)
`amount`	number	Valor do extrato na moeda indicada em `currency`
`total_due_usd`	number	Total do extrato convertido para USD
`currency`	string	Código de moeda ISO 4217 (padrão: `USD`)

`transcode.completed` e `transcode.failed`

Disparado quando a transcodificação de áudio de uma faixa é concluída. transcode.completed dispara em caso de sucesso; transcode.failed dispara quando a transcodificação falha ou termina incompleta. Ambos têm o mesmo formato de payload.

{
  "event": "transcode.completed",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "release_id": 789,
    "label_id": 321,
    "track_id": 654,
    "transcoder_queue_id": 987,
    "status": "complete",
    "status_message": "transcode_complete",
    "files": [
      { "asset_type_id": 2, "status": "complete" }
    ]
  }
}

Campo	Tipo	Descrição
`release_id`	integer	O lançamento ao qual a faixa pertence
`label_id`	integer	O selo dono do lançamento
`track_id`	integer	A faixa que foi transcodificada
`transcoder_queue_id`	integer	ID interno da fila de transcodificação
`status`	string	Status bruto da fila: `complete`, `error` ou `incomplete`
`status_message`	string	Código de motivo seguro e enumerado: `transcode_complete`, `transcode_error` ou `transcode_incomplete`
`files`	array	Detalhe por arquivo da faixa: `{asset_type_id, status}` por arquivo transcodificado

`distribution.outlet.status_changed`

Disparado em cada transição de status de distribuição por loja (por exemplo, scheduled → transcoding → batched → complete), não apenas nas finais cobertas por delivery.completed, delivery.failed e takedown.completed. Este evento é verboso por natureza: assine-o apenas se você quiser toda a progressão por loja.

{
  "event": "distribution.outlet.status_changed",
  "timestamp": "2026-07-07T10:00:00+00:00",
  "webhook_id": "123",
  "data": {
    "distro_queue_id": 456,
    "release_id": 789,
    "label_id": 321,
    "release_cat": "ABC123",
    "outlet_id": 12,
    "outlet_name": "Spotify",
    "previous_status": "transcoding",
    "status": "batched"
  }
}

Campo	Tipo	Descrição
`distro_queue_id`	integer	ID interno da fila para esta entrega
`release_id`	integer	O lançamento que está sendo distribuído
`label_id`	integer	O selo dono do lançamento
`release_cat`	string \| null	A referência de catálogo do seu lançamento
`outlet_id`	integer \| null	O ID da loja de destino
`outlet_name`	string \| null	Nome legível da loja
`previous_status`	string \| null	O status anterior; `null` quando a linha não tinha um status anterior reconhecido
`status`	string	O novo status

Como verificar as assinaturas dos webhooks

Toda entrega de webhook é assinada para que você possa verificar que ela realmente veio do LabelGrid. Sempre verifique a assinatura antes de processar o evento.

Cabeçalhos da requisição

Toda requisição POST de webhook inclui estes cabeçalhos:

Cabeçalho	Descrição
`X-Webhook-Signature`	HMAC-SHA256 do corpo bruto da requisição, em hexadecimal minúsculo, sem prefixo de algoritmo
`X-Webhook-Timestamp`	Cópia de conveniência da propriedade `timestamp` do corpo. Não é coberto pela assinatura — nunca use esse cabeçalho para decidir se uma entrega é recente.
`X-Webhook-Event`	Identificador do evento (ex.: `delivery.completed`)
`X-Webhook-Id`	O ID da configuração do webhook que está recebendo a entrega (não é um ID por entrega)
`User-Agent`	`LabelGrid-Webhooks/1.0`
`Content-Type`	`application/json`

Algoritmo

Algoritmo: HMAC-SHA256
Codificação: Hexadecimal minúsculo
Prefixo: Nenhum. O valor é apenas o digest em hexadecimal, não sha256=...
Conteúdo assinado: O corpo bruto completo da requisição JSON — e nada mais. Nenhum cabeçalho é assinado.

O corpo traz a sua própria propriedade timestamp, então esse valor é protegido pela assinatura. O cabeçalho X-Webhook-Timestamp é apenas uma cópia dele, enviada por conveniência, e quem interceptar uma entrega pode alterar o cabeçalho à vontade sem invalidar a assinatura. Por isso, para saber se uma entrega é recente, leia o timestamp do corpo já interpretado, nunca do cabeçalho.

Receita de verificação

Leia o corpo bruto da requisição antes de qualquer parsing ou transformação de JSON. Reserializar o JSON já interpretado pode produzir bytes diferentes e invalidar a assinatura.
Calcule HMAC-SHA256(raw_body, your_webhook_secret) e use o digest em hexadecimal minúsculo.
Compare com X-Webhook-Signature usando uma comparação de tempo constante. Se não bater, pare por aqui.
Só então interprete o corpo e rejeite a requisição se a propriedade timestamp dele for mais antiga do que a sua janela de tolerância contra replay (sugerimos 5 minutos). Como esse valor é assinado, quem interceptar a entrega não consegue atualizá-lo para fazer a entrega parecer recente.

Cada reenvio é assinado de novo com um timestamp novo, então uma janela de 5 minutos nunca rejeita um reenvio legítimo, por mais avançado que ele esteja no cronograma de reenvios.

Exemplo em PHP

$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$expected = hash_hmac('sha256', $rawBody, $webhookSecret);

if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Interprete o corpo só depois de comprovar que os bytes são autênticos.
$payload = json_decode($rawBody, true);

// Para saber se a entrega é recente, use o timestamp ASSINADO do corpo,
// nunca o cabeçalho X-Webhook-Timestamp.
if (! isset($payload['timestamp'])
    || abs(time() - strtotime($payload['timestamp'])) > 300) {
    http_response_code(401);
    exit('Stale delivery');
}

// ... processe o evento (veja "Como lidar com entregas repetidas" abaixo)
http_response_code(200);

Exemplo em Node.js

const crypto = require('crypto');

// Express: capture o corpo bruto ANTES de qualquer middleware JSON
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body; // Buffer
  const signature = req.header('X-Webhook-Signature') || '';

  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');

  const sigBuf = Buffer.from(signature, 'hex');
  const expBuf = Buffer.from(expected, 'hex');

  if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
    return res.status(401).send('Invalid signature');
  }

  // Interprete o corpo só depois de comprovar que os bytes são autênticos.
  const payload = JSON.parse(rawBody.toString('utf8'));

  // Para saber se a entrega é recente, use o timestamp ASSINADO do corpo,
  // nunca o cabeçalho X-Webhook-Timestamp.
  const sentAt = new Date(payload.timestamp).getTime();

  if (Number.isNaN(sentAt) || Math.abs(Date.now() - sentAt) > 5 * 60 * 1000) {
    return res.status(401).send('Stale delivery');
  }

  // ... processe o evento (veja "Como lidar com entregas repetidas" abaixo)
  res.sendStatus(200);
});

Exemplo em Python

import hmac, hashlib, json
from datetime import datetime, timezone

raw_body = request.get_data()  # Flask: bytes, antes de qualquer parsing de JSON
signature = request.headers.get('X-Webhook-Signature', '')

expected = hmac.new(
    webhook_secret.encode('utf-8'),
    raw_body,
    hashlib.sha256
).hexdigest()

if not hmac.compare_digest(expected, signature):
    return ('Invalid signature', 401)

payload = json.loads(raw_body)  # interprete só com os bytes já autenticados

delivery_time = datetime.fromisoformat(payload['timestamp'])  # o valor ASSINADO, nunca o cabeçalho
if abs((datetime.now(timezone.utc) - delivery_time).total_seconds()) > 300:
    return ('Stale delivery', 401)

return ('', 200)  # processe o evento e depois confirme

Armadilhas comuns

Verificar se a entrega é recente usando o cabeçalho X-Webhook-Timestamp. O cabeçalho não é assinado. Quem interceptar uma entrega pode reenviar exatamente o mesmo corpo e a mesma assinatura com um valor de cabeçalho novo e passar para sempre por uma verificação baseada no cabeçalho. Leia o timestamp do corpo já interpretado: esse valor é assinado.
Reserializar o corpo antes de calcular o hash. Frameworks que interpretam JSON automaticamente (express.json() do Express, corpo de requisição padrão do Laravel) perdem os bytes originais. Capture o corpo bruto primeiro.
Usar uma comparação que não seja de tempo constante (==, ===). Fica vulnerável a ataques de temporização. Use sempre hash_equals (PHP), crypto.timingSafeEqual (Node), hmac.compare_digest (Python) ou o equivalente na sua linguagem.
Esperar um prefixo sha256=. O valor do cabeçalho é apenas o digest em hexadecimal, sem prefixo.
Pular a verificação de que a entrega é recente. Sem ela, uma entrega interceptada pode ser reenviada ao seu endpoint indefinidamente.
Tratar o X-Webhook-Id como um ID de entrega. Ele identifica a configuração do webhook, não a entrega individual, e também não é assinado.

Como lidar com entregas repetidas

A entrega de webhooks é at-least-once (pelo menos uma vez): uma entrega que o seu endpoint realmente processou pode chegar de novo se a sua resposta 2xx se perdeu ou chegou depois do tempo limite de 10 segundos, e aí o LabelGrid a reenvia. Verificar a assinatura prova que a requisição é autêntica, mas não prova que você ainda não a tratou.

As entregas não trazem um ID único por entrega, então monte a sua própria chave de idempotência a partir do payload assinado. Normalmente basta o tipo do evento mais os identificadores que estão em data — por exemplo, delivery.completed mais distro_queue_id, ou transcode.completed mais track_id. Registre a chave quando processar um evento e ignore tudo o que já tiver registrado.

Não use a assinatura nem o timestamp como essa chave. Cada tentativa é assinada de novo no momento do envio, então o reenvio de um evento que você já tratou chega com um timestamp diferente e uma assinatura diferente: a chave precisa vir dos identificadores do próprio evento.

Combine isso com a verificação acima de que a entrega é recente: ela limita por quanto tempo uma entrega interceptada continua reenviável, e a idempotência torna uma repetição inofensiva, venha ela de um reenvio ou de um atacante dentro da janela.

Limites e confiabilidade

Limites de requisição

Limite	Valor
Tempo limite da requisição	10 segundos
Tamanho máximo do payload	64 KB
Máximo de webhooks por usuário	10

Se o seu endpoint não responder em até 10 segundos, a entrega é tratada como falha e reenviada.

Cronograma de reenvios

Se o seu endpoint retornar um status fora da faixa 2xx ou exceder o tempo limite, o LabelGrid reenvia com backoff exponencial:

Tentativa	Espera antes do reenvio
1 → 2	30 segundos
2 → 3	1 minuto
3 → 4	2 minutos
4 → 5	4 minutos
5 → 6	8 minutos
6 → 7	16 minutos
7 → 8	32 minutos
8 → 9	64 minutos
9 → 10	128 minutos

Cada intervalo inclui de 0 a 30 segundos de jitter. Após 10 tentativas (cerca de 4,5 horas de tempo total decorrido), a entrega é registrada como falha permanente e não é mais reenviada.

Desativação automática

Se o endpoint de um webhook continua falhando — entregas com falha consecutivas sem nenhuma entrega bem-sucedida entre elas —, o LabelGrid desativa o webhook automaticamente para parar de tentar reenviar para um endpoint que claramente não consegue receber eventos. O contador de falhas é zerado a cada entrega bem-sucedida, então uma falha ocasional nunca desativa um webhook; apenas uma falha contínua e ininterrupta faz isso.

Quando um webhook é desativado dessa forma, o seu proprietário recebe um e-mail. O e-mail informa o nome do webhook e a URL do seu endpoint, além do tipo de falha que provocou a desativação — por exemplo, um tempo limite de conexão esgotado ou erros HTTP repetidos.

A reativação é self-service: corrija o seu endpoint e ative o webhook novamente em Perfil → Webhooks. Reativar um webhook desativado zera a contagem de falhas. A lista de webhooks mostra o status ativo e a contagem de falhas atual de cada webhook, para que você identifique um endpoint com problemas rapidamente.

Boas práticas de confiabilidade

Retorne uma resposta 2xx rapidamente (em até 10 segundos)
Processe os dados de forma assíncrona depois de confirmar o recebimento
Verifique a assinatura em toda requisição (consulte Como verificar as assinaturas dos webhooks)
Deixe o seu handler idempotente: a entrega é at-least-once (consulte Como lidar com entregas repetidas)
Acompanhe a contagem de falhas na lista de webhooks
Consulte os logs de entrega ao investigar eventos perdidos

Casos de uso

Notificações automatizadas

Envie mensagens no Slack quando os lançamentos entram no ar
Envie e-mails para a sua equipe quando as entregas falham
Atualize painéis internos

Automação de fluxos de trabalho

Acione campanhas de marketing quando os lançamentos são distribuídos
Atualize seu site quando há novo conteúdo disponível
Sincronize o status com ferramentas externas de gestão de projetos

Monitoramento e alertas

Receba alertas imediatos sobre falhas de entrega
Acompanhe o progresso da distribuição em tempo real
Monitore as mudanças de status de revisão

Solução de problemas

O webhook não recebe eventos

Verifique o status - O webhook está Active?
Confira a URL - O endpoint está acessível pela internet?
Verifique os eventos - Os eventos certos estão selecionados?
Revise os logs - Há algum erro registrado?

Contagem alta de falhas

Verifique o seu endpoint - Ele está retornando 200 OK?
Verifique o tempo de resposta - Ele responde dentro do tempo limite?
Revise as mensagens de erro - O que está falhando?
Teste manualmente - Envie um webhook de teste

Como gerar uma nova chave secreta

Se a chave secreta do seu webhook for comprometida:

Clique em Regenerate Secret nas configurações do webhook
Atualize a sua aplicação com a nova chave secreta
A chave antiga deixa de funcionar imediatamente

Precisa de ajuda?

Se você tem dúvidas sobre webhooks, fale com nossa equipe de suporte.

Ainda não usa a LabelGrid?

Tudo o que você acabou de ler está disponível na nossa plataforma.

Veja o que a LabelGrid pode fazer →