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

# Uso de webhooks

export const LastUpdatedPt = ({date}) => {
  const label = "Última atualização:";
  return <>
      <style>{`
        .last-updated-component {
          display: inline-flex;
          align-items: center;
          gap: 8px;
          padding: 10px 16px;
          border-radius: 8px;
          margin-top: 12px;
          margin-bottom: 16px;
          font-size: 14px;
          background-color: rgba(0, 0, 0, 0.05);
          border: 1px solid rgba(0, 0, 0, 0.12);
          color: rgba(0, 0, 0, 0.75);
          line-height: 1;
        }

        .last-updated-component svg {
          flex-shrink: 0;
          vertical-align: middle;
        }

        .last-updated-component span {
          display: inline-flex !important;
          align-items: center !important;
          line-height: 1 !important;
        }

        [data-theme="dark"] .last-updated-component {
          background-color: #3a3a3a;
          border: 2px solid #888888;
          color: #ffffff;
        }

        [data-theme="dark"] .last-updated-component svg {
          stroke: #ffffff;
        }
      `}</style>
      <div className="last-updated-component">
        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          <circle cx="12" cy="12" r="10" />
          <polyline points="12 6 12 12 16 14" />
        </svg>
        <span>
          <strong style={{
    fontWeight: 600
  }}>{label}</strong> 
          <time dateTime={date}>{date}</time>
        </span>
      </div>
    </>;
};

<div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
  Os webhooks fornecem notificações em tempo real sobre eventos como a creação, actualização ou eliminação de campanhas. Para receber essas notificações, você deve especificar uma URL de acesso público capaz de receber solicitações POST HTTP.
</div>

## Como Funciona

<div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
  Quando um evento ocorre, uma solicitação POST HTTP contendo os detalhes do evento é enviada à sua URL especificada. Sua URL deve retornar um código de status HTTP 2xx para solicitações bem-sucedidas.
</div>

<div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
  Os webhooks são criados através da API Criar webhook (API), onde você define o evento acionador utilizando o campo de canal. Apenas um webhook é permitido por canal.
</div>

### Tentativas e validação

<div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
  Se a URL do seu webhook não estiver acessível, tentaremos enviar a solicitação até 5 vezes em 1 minuto, utilizando retrocesso exponencial. As tentativas ocorrem apenas para códigos de status HTTP 5xx ou 429.
</div>

<div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
  Para garantir a autenticidade e integridade das entregas de webhook, você deve validar a assinatura. A Topsort gera uma assinatura utilizando o seu segredo de webhook e o payload do evento, incluindo-a no cabeçalho HTTP X-TS-Signature-256.
</div>

<div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
  Você pode definir o seu segredo de webhook durante a criação; caso contrário, um será gerado automaticamente. Armazene o seu segredo de forma segura.
</div>

<div style={{textAlign: 'justify', marginBottom: '1.5rem'}}>
  A Topsort utiliza o resumo hexadecimal HMAC (que começa com sha256=) para calcular a assinatura. Você deve recalcular o hash no seu servidor e compará-lo com o cabeçalho X-TS-Signature-256 para verificar a assinatura.
</div>

### Exemplo de verificação de assinatura

```python theme={null}
import hmac
import hashlib

secret = "my-webhook-secret"
request = ... # incoming request from the webhook delivery

signature = hmac.new(
    key=secret.encode(),
    msg=await request.body(),
    digestmod=hashlib.sha256,
).hexdigest()

expected_signature = "sha256=" + signature
incoming_signature = request.headers["X-TS-Signature-256"]

if not hmac.compare_digest(incoming_signature, expected_signature):
    # The signature is not valid, do not process the delivery
else:
    # The signature is valid, process the delivery
```

***

<LastUpdatedPt date="2025-11-18" />