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çalhowebhook-id.type: o tipo do evento.createdAt: quando o evento ocorreu, em ISO-8601 UTC.data.pretest: o pré-teste, exatamente comoGET /pretests/{id}o devolve no momento do evento (o exemplo acima mostra só alguns campos). Veja Resultados.
ping chega com data vazio ({}).
Cabeçalhos
Criar um endpoint
201 e traz o endpoint, com id, status (enabled ou disabled) e o campo secret, no formato whsec_SEU_SEGREDO_AQUI.
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.
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 umPOST 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.
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:- Tire o prefixo
whsec_do segredo e decodifique o resto de base64. O resultado é a chave. - Monte o texto
webhook-id+.+webhook-timestamp+.+ corpo cru. - Calcule o HMAC-SHA256 desse texto com a chave e codifique em base64.
- Compare com cada item de
webhook-signature(separados por espaço, cada um no formatov1,<base64>), em tempo constante. - Rejeite a requisição se
webhook-timestampdiferir do seu relógio em mais de 5 minutos.
false, nunca lança erro: responda 400.
Responder e processar
- Responda com
2xxem 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 seja2xx (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_readypode chegar antes depretest.completed, e uma tentativa antiga pode chegar depois de uma mais nova. - Um evento pode chegar mais de uma vez. Use o
webhook-idpara 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, consulteGET /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.
Ler a lista de envios
GET /webhook-endpoints/{id}/deliveries devolve os últimos 50 envios daquele endpoint, do mais novo para o mais antigo.
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.