Webhooks

Em vez de consultar a API periodicamente, pode fazer com que o Pulsar chame a sua aplicação quando algo acontece. Um webhook é um endpoint HTTPS alojado por si. O Pulsar envia-lhe um pedido POST com um corpo JSON sempre que ocorre um evento que subscreveu.

De momento, os webhooks abrangem as paragens de máquina e as suas classificações: o Pulsar avisa-o quando uma paragem começa e termina, quando uma paragem é classificada, quando uma classificação muda e quando uma é eliminada.

Configure um webhook

Requisitos do endpoint

O Pulsar só entrega a endpoints que sejam:

• HTTPS públicos. O URL tem de usar https://, ter no máximo 255 caracteres e não incluir credenciais (user:pass@) nem #fragmento. O nome de anfitrião tem de resolver para endereços IP públicos. Os endereços privados, de loopback e link-local são recusados.
• Rápidos. Cada pedido tem um limite de 10 segundos, incluindo a resolução DNS e o estabelecimento da ligação.
• Definitivos. Os redirecionamentos não são seguidos. Uma resposta 3XX conta como entrega falhada, por isso registe o URL final.

O pedido

Cada notificação é um POST com um corpo JSON e estes cabeçalhos:

POST /webhooks/pulsar HTTP/1.1
Host: example.com
Content-Type: application/json
X-Pulsar-Signature: 5c0e2f4a1b9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f
X-Pulsar-Event-Type: MachineStopClassificationCreated
X-Pulsar-Event-Id: 8d2f6c1e-4b7a-4f0e-9a3c-5e1d7b9f2a64
X-Pulsar-Timestamp: 2026-09-25T14:03:12.482Z
X-Pulsar-Request-Id: 3f9b2c7d-1e4a-4c8b-b6d2-9a0e5f7c1b38

{
  "eventId": "8d2f6c1e-4b7a-4f0e-9a3c-5e1d7b9f2a64",
  "eventTimestamp": "2026-09-25T14:03:12.482Z",
  "eventType": "MachineStopClassificationCreated",
  "event": { ... }
}

Cabeçalhos

Os nomes dos cabeçalhos não distinguem maiúsculas de minúsculas, por isso a sua framework pode mostrá-los em minúsculas.

Corpo

Todas as notificações têm o mesmo envelope:

Responda com um 2XX, rapidamente

Devolva um estado 2XX assim que tiver verificado a assinatura. O Pulsar só lê o código de estado e ignora o corpo da resposta.

• Devolva 200 se já processou o evento.
• Devolva 202 se o colocou em fila para mais tarde.

Faça qualquer tarefa lenta, como chamar outros sistemas ou trabalho pesado de base de dados, numa tarefa em segundo plano depois de responder. Uma resposta que demore mais de 10 segundos conta como falha e é repetida, mesmo que o seu código acabe por terminar.

Novas tentativas

O que o Pulsar faz com uma entrega falhada depende do motivo da falha:

Um endpoint que falha não atrasa as entregas aos seus outros endpoints.

Duplicados e ordem

A entrega é pelo menos uma vez. Ocasionalmente, o mesmo evento chega ao seu endpoint mais de uma vez, por exemplo quando o seu endpoint processou um pedido mas o Pulsar não registou a resposta a tempo. Um evento repetido também chega mais tarde do que os eventos entregues à primeira tentativa, por isso a ordem não é garantida.

Faça com que o seu handler possa ser executado duas vezes sem problemas: guarde cada eventId que processar e ignore os que já tiver visto. Uma nova tentativa ou um reenvio leva sempre o eventId original.

Eventos Ping

Um ping testa o seu endpoint sem esperar por um evento real. Usa os mesmos cabeçalhos e a mesma assinatura que qualquer outra notificação, tem eventType igual a Ping e o seu event é sempre { "text": "ping" }:

{
  "eventId": "0b6f3d2a-9c1e-4a7b-8f5d-2e4c6a8b0d1f",
  "eventTimestamp": "2026-09-25T14:00:00.000Z",
  "eventType": "Ping",
  "event": {
    "text": "ping"
  }
}

Um ping pode chegar a um endpoint seja qual for o tipo de evento para que está registado, por isso responda 2XX a Ping em vez de rejeitar os tipos de evento que não esperava.

Próximos passos