Pular para o conteúdo principal
Em vez de consultar GET /pretests/{id} de tempos em tempos, cadastre um endereço do seu servidor. A Unite faz um POST assinado nesse endereço quando algo muda em um pré-teste. O formato segue o padrão Standard Webhooks. Para gerenciar endpoints pela API, a chave precisa do escopo webhooks:manage. Veja Autenticação. Administradores do workspace também cadastram, testam e removem endpoints no painel do workspace, sem usar chave.

Eventos

Cada endpoint escolhe os eventos que quer receber. Há também o evento ping, usado só para testar o endpoint.

Corpo do envio

O corpo é JSON:
  • id: identifica o evento. É o mesmo valor do cabeçalho webhook-id.
  • type: o tipo do evento.
  • createdAt: quando o evento ocorreu, em ISO-8601 UTC.
  • data.pretest: o pré-teste, exatamente como GET /pretests/{id} o devolve no momento do evento (o exemplo acima mostra só alguns campos). Veja Resultados.
O evento ping chega com data vazio ({}).

Cabeçalhos

Criar um endpoint

A resposta é 201 e traz o endpoint, com id, status (enabled ou disabled) e o campo secret, no formato whsec_SEU_SEGREDO_AQUI.
O segredo aparece uma única vez, nesta resposta. A lista de endpoints nunca o devolve. Guarde-o em uma variável de ambiente do seu back-end. Se perder, apague o endpoint e crie outro.
Regras do endereço:
  • Precisa usar https, na porta 443 (a padrão).
  • Não pode ter usuário nem senha.
  • Precisa resolver para um endereço público da internet. Endereços privados e locais são recusados.
Um endereço recusado responde webhook_url_rejected. Cada workspace pode ter até 5 endpoints, ativos ou não. Passando disso, a resposta é webhook_endpoint_limit. Para listar, use GET /webhook-endpoints. Para apagar, DELETE /webhook-endpoints/{id}: o endpoint e o histórico de envios dele são removidos, e os envios que ainda esperavam são descartados.

Verificar a assinatura

Toda requisição vem assinada com o segredo do endpoint. Confira a assinatura antes de confiar no conteúdo: qualquer pessoa que descubra o seu endereço pode mandar um POST falso. Use a biblioteca oficial do Standard Webhooks. Ela confere a assinatura e rejeita um webhook-timestamp com mais de 5 minutos de diferença, o que barra o reenvio de uma requisição antiga capturada por terceiros.
Assine e confira o corpo exatamente como chegou (os bytes crus). Se o seu framework converter o JSON em objeto e depois voltar para texto, a assinatura deixa de bater. Leia o corpo cru antes de qualquer conversão.
Isto só tira o processamento de dentro da resposta. Trabalho de verdade em segundo plano (gravar em banco, chamar outros sistemas, repetir em caso de erro) pertence à sua fila de tarefas: guarde o evento, devolva 200 e deixe um worker processar. verify devolve o evento já convertido em objeto e lança WebhookVerificationError se a assinatura não bater ou se o webhook-timestamp for antigo demais. Responda 400 nesses casos.

Sem a biblioteca

Se preferir não usar a biblioteca, a assinatura é calculada assim:
  1. Tire o prefixo whsec_ do segredo e decodifique o resto de base64. O resultado é a chave.
  2. Monte o texto webhook-id + . + webhook-timestamp + . + corpo cru.
  3. Calcule o HMAC-SHA256 desse texto com a chave e codifique em base64.
  4. Compare com cada item de webhook-signature (separados por espaço, cada um no formato v1,<base64>), em tempo constante.
  5. Rejeite a requisição se webhook-timestamp diferir do seu relógio em mais de 5 minutos.
A mesma conta em Python:
Os nomes de cabeçalho não diferenciam maiúsculas de minúsculas (o Python acima os converte para minúsculas antes de ler). Nos dois exemplos, uma falha de formato (cabeçalho ausente ou fora do padrão) devolve false, nunca lança erro: responda 400.

Responder e processar

  • Responda com 2xx em até 10 segundos. Passando disso, a tentativa conta como falha.
  • Faça o mínimo antes de responder: confira a assinatura, guarde o evento e devolva 200. Processe o resto em segundo plano.
  • Redirecionamentos (3xx) não são seguidos e contam como falha. Cadastre o endereço final.
  • A Unite não usa endereços de IP fixos para enviar. Não libere por IP: a verificação da assinatura é o que garante a origem.

Novas tentativas

Qualquer resposta que não seja 2xx (ou falta de resposta em 10 segundos) provoca uma nova tentativa. São até 12 tentativas por envio, com intervalo crescente de 30 segundos até 1 hora, ao longo de cerca de 5 a 6 horas. Se todas falharem, o envio fica como failed. Um envio que continue pendente por mais de 7 horas também aparece como failed, com lastError igual a expired. A exceção é o status 410: ele significa “este endereço não existe mais”. Quando o seu destino responde 410, a Unite desativa o endpoint (status: "disabled", disabledReason: "gone") e não tenta de novo. Outra exceção: se o endereço passar a resolver para um endereço privado ou bloqueado, o envio é encerrado sem nova tentativa, com lastError como url_rejected:private_address. Se o acesso à API for desligado no workspace, o envio também é encerrado sem nova tentativa, com lastError como feature_disabled. Um endpoint desativado não recebe mais eventos e não pode ser testado; crie outro para voltar a receber. Só responda 410 de propósito. Um endpoint também é desativado sozinho, com disabledReason: "creator_removed", quando quem o criou sai do workspace ou perde o acesso a ele. Ele deixa de receber eventos e não pode ser testado; um administrador cadastra outro endpoint. Revogar uma chave de API não afeta os endpoints: eles pertencem ao workspace, e os administradores os gerenciam no painel do workspace.

Ordem e repetição

  • Não há garantia de ordem. pretest.report_ready pode chegar antes de pretest.completed, e uma tentativa antiga pode chegar depois de uma mais nova.
  • Um evento pode chegar mais de uma vez. Use o webhook-id para ignorar o que você já processou. Guarde os ids recebidos e descarte repetidos.
  • A verdade está no GET. O evento avisa que algo mudou. Para o estado atual, consulte GET /pretests/{id}, e não confie na ordem de chegada.

Testar o endpoint

POST /webhook-endpoints/{id}/test envia um evento ping assinado, igual aos demais. A resposta é 202, com o id do envio e status: "pending". O resultado aparece na lista de envios.
Um endpoint desativado não pode ser testado.

Ler a lista de envios

GET /webhook-endpoints/{id}/deliveries devolve os últimos 50 envios daquele endpoint, do mais novo para o mais antigo.
Cada item traz: Se muitos envios aparecem como failed, confira se o seu servidor responde 2xx em até 10 segundos, se o certificado é válido e se o endereço não redireciona.