Webhooks

Os endereços do seu servidor que a N-Ways chama quando uma entrega ou um veículo muda.

Nesta página

Listar endpoints de webhook
Adicionar um endpoint (até 10); a resposta traz o seu segredo de assinatura, mostrado uma única vez
Alterar o url, os eventos ou o active de um endpoint
Eliminar um endpoint e o seu registo de entregas
Um novo segredo de assinatura (mostrado uma única vez); o antigo deixa de funcionar de imediato
Pôr em fila um evento ping para o endpoint
O registo de entregas do endpoint, das mais recentes para as mais antigas (guardado 30 dias)
Enviar de novo uma entrega agora (falhada, ou entregue e pretendida outra vez); as suas tentativas são mantidas
Um evento, enviado por POST para o seu endpoint

Nota:

Envie a sua chave com key=A_SUA_CHAVE_API no endereço, ou no cabeçalho X-NWays-Api-Key. Chaves de API

Endereço base: https://nways.ng/maps/v1/fleet

Listar endpoints de webhook

GET https://nways.ng/maps/v1/fleet/webhooks

cURL

curl "https://nways.ng/maps/v1/fleet/webhooks" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/webhooks', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/fleet/webhooks",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Os endpoints e os eventos existentes

Campo	Tipo	Descrição
`webhooks`	`Webhook[]`	Obrigatório.
`webhooks[].id`	`string`	Obrigatório.
`webhooks[].url`	`string (uri)`	Obrigatório.
`webhooks[].events`	`string[]`	Obrigatório.
`webhooks[].active`	`boolean`	Obrigatório.
`webhooks[].secret`	`string`	Apenas quando é criado ou renovado.
`webhooks[].headers`	`string[]`	Nomes dos cabeçalhos personalizados enviados com cada entrega (os valores nunca são mostrados).
`webhooks[].createdAt`	`string (date-time)`	Obrigatório.
`webhooks[].updatedAt`	`string (date-time)`	Obrigatório.
`events`	`string[]`	Obrigatório.

200 OK

{
  "webhooks": [
    {
      "id": "wh_Ub3yH9sLk2",
      "url": "string",
      "events": [
        "task.created"
      ],
      "active": true,
      "secret": "whsec_…",
      "headers": [
        "string"
      ],
      "createdAt": "2026-10-15T09:00:00+01:00",
      "updatedAt": "2026-10-15T09:00:00+01:00"
    }
  ],
  "events": [
    "task.created"
  ]
}

Erros

default Erro

Adicionar um endpoint (até 10); a resposta traz o seu segredo de assinatura, mostrado uma única vez

POST https://nways.ng/maps/v1/fleet/webhooks

Corpo do pedido

Campo	Tipo	Descrição
`url`	`string (uri)`	Obrigatório. https, um endereço público; os redirecionamentos não são seguidos.
`events`	`string[]`	Vazio = todos os eventos.
`headers`	`object`	Enviados com cada entrega (um token de autenticação que o seu CRM pede). Nunca X-NWays-*, Host, Content-Type, User-Agent.

cURL

curl -X POST "https://nways.ng/maps/v1/fleet/webhooks" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"url":"string","events":["task.created"],"headers":{}}'

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/webhooks', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "url": "string",
    "events": [
      "task.created"
    ],
    "headers": {}
  }),
})
const data = await res.json()

Python

import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/fleet/webhooks",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"url": "string", "events": ["task.created"], "headers": {}},
    timeout=10,
)
data = res.json()

Resposta

Criado

Campo	Tipo	Descrição
`id`	`string`	Obrigatório.
`url`	`string (uri)`	Obrigatório.
`events`	`string[]`	Obrigatório.
`active`	`boolean`	Obrigatório.
`secret`	`string`	Apenas quando é criado ou renovado.
`headers`	`string[]`	Nomes dos cabeçalhos personalizados enviados com cada entrega (os valores nunca são mostrados).
`createdAt`	`string (date-time)`	Obrigatório.
`updatedAt`	`string (date-time)`	Obrigatório.

201 OK

{
  "id": "wh_Ub3yH9sLk2",
  "url": "string",
  "events": [
    "task.created"
  ],
  "active": true,
  "secret": "whsec_…",
  "headers": [
    "string"
  ],
  "createdAt": "2026-10-15T09:00:00+01:00",
  "updatedAt": "2026-10-15T09:00:00+01:00"
}

Erros

default Erro

Alterar o url, os eventos ou o active de um endpoint

PATCH https://nways.ng/maps/v1/fleet/webhooks/{id}

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	caminho	`string`	Obrigatório.

Corpo do pedido

Campo	Tipo	Descrição
`url`	`string (uri)`
`events`	`string[]`
`active`	`boolean`	Desligado: as entregas pendentes falham e não são postas novas em fila.

cURL

curl -X PATCH "https://nways.ng/maps/v1/fleet/webhooks/string" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"url":"string","events":["task.created"],"active":true}'

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/webhooks/string', {
  method: 'PATCH',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "url": "string",
    "events": [
      "task.created"
    ],
    "active": true
  }),
})
const data = await res.json()

Python

import os
import requests

res = requests.patch(
    "https://nways.ng/maps/v1/fleet/webhooks/string",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"url": "string", "events": ["task.created"], "active": True},
    timeout=10,
)
data = res.json()

Resposta

Endpoint

Campo	Tipo	Descrição
`id`	`string`	Obrigatório.
`url`	`string (uri)`	Obrigatório.
`events`	`string[]`	Obrigatório.
`active`	`boolean`	Obrigatório.
`secret`	`string`	Apenas quando é criado ou renovado.
`headers`	`string[]`	Nomes dos cabeçalhos personalizados enviados com cada entrega (os valores nunca são mostrados).
`createdAt`	`string (date-time)`	Obrigatório.
`updatedAt`	`string (date-time)`	Obrigatório.

200 OK

{
  "id": "wh_Ub3yH9sLk2",
  "url": "string",
  "events": [
    "task.created"
  ],
  "active": true,
  "secret": "whsec_…",
  "headers": [
    "string"
  ],
  "createdAt": "2026-10-15T09:00:00+01:00",
  "updatedAt": "2026-10-15T09:00:00+01:00"
}

Erros

default Erro

Eliminar um endpoint e o seu registo de entregas

DELETE https://nways.ng/maps/v1/fleet/webhooks/{id}

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	caminho	`string`	Obrigatório.

cURL

curl -X DELETE "https://nways.ng/maps/v1/fleet/webhooks/string" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/webhooks/string', {
  method: 'DELETE',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.delete(
    "https://nways.ng/maps/v1/fleet/webhooks/string",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Eliminado

Sem conteúdo.

Erros

default Erro

Um novo segredo de assinatura (mostrado uma única vez); o antigo deixa de funcionar de imediato

POST https://nways.ng/maps/v1/fleet/webhooks/{id}/rotate-secret

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	caminho	`string`	Obrigatório.

cURL

curl -X POST "https://nways.ng/maps/v1/fleet/webhooks/string/rotate-secret" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/webhooks/string/rotate-secret', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/fleet/webhooks/string/rotate-secret",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Endpoint com secret

Campo	Tipo	Descrição
`id`	`string`	Obrigatório.
`url`	`string (uri)`	Obrigatório.
`events`	`string[]`	Obrigatório.
`active`	`boolean`	Obrigatório.
`secret`	`string`	Apenas quando é criado ou renovado.
`headers`	`string[]`	Nomes dos cabeçalhos personalizados enviados com cada entrega (os valores nunca são mostrados).
`createdAt`	`string (date-time)`	Obrigatório.
`updatedAt`	`string (date-time)`	Obrigatório.

200 OK

{
  "id": "wh_Ub3yH9sLk2",
  "url": "string",
  "events": [
    "task.created"
  ],
  "active": true,
  "secret": "whsec_…",
  "headers": [
    "string"
  ],
  "createdAt": "2026-10-15T09:00:00+01:00",
  "updatedAt": "2026-10-15T09:00:00+01:00"
}

Erros

default Erro

Pôr em fila um evento `ping` para o endpoint

POST https://nways.ng/maps/v1/fleet/webhooks/{id}/test

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	caminho	`string`	Obrigatório.

cURL

curl -X POST "https://nways.ng/maps/v1/fleet/webhooks/string/test" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/webhooks/string/test', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/fleet/webhooks/string/test",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Em fila

Campo	Tipo	Descrição
`deliveryId`	`string`	Obrigatório.

202 OK

{
  "deliveryId": "dlv_Qa71ZcR0mX"
}

Erros

default Erro

O registo de entregas do endpoint, das mais recentes para as mais antigas (guardado 30 dias)

GET https://nways.ng/maps/v1/fleet/webhooks/{id}/deliveries

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	caminho	`string`	Obrigatório.
`status`	consulta	`string`	Um de: `pending`, `delivered`, `failed`.
`limit`	consulta	`integer`	Predefinição: `50`. ≥ 1, ≤ 200.

cURL

curl "https://nways.ng/maps/v1/fleet/webhooks/string/deliveries" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/webhooks/string/deliveries', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/fleet/webhooks/string/deliveries",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Entregas

Campo	Tipo	Descrição
`deliveries`	`Delivery[]`	Obrigatório.
`deliveries[].id`	`string`	Obrigatório.
`deliveries[].event`	`string`	Obrigatório.
`deliveries[].status`	`string`	Obrigatório. Um de: `pending`, `delivered`, `failed`.
`deliveries[].attempts`	`integer`	Obrigatório.
`deliveries[].lastStatus`	`integer`	Obrigatório. O último estado HTTP do seu endpoint (0 = sem resposta).
`deliveries[].lastError`	`string`	Obrigatório.
`deliveries[].nextAttemptAt`	`string (date-time) \| null`	Obrigatório.
`deliveries[].createdAt`	`string (date-time)`	Obrigatório.
`deliveries[].deliveredAt`	`string (date-time) \| null`	Obrigatório.
`deliveries[].payload`	`Event`	Obrigatório.
`deliveries[].payload.id`	`string`	Obrigatório.
`deliveries[].payload.type`	`string`	Obrigatório. Um EventType, ou `ping` vindo da chamada de teste.
`deliveries[].payload.version`	`string`	Obrigatório. A versão da forma do conteúdo: dentro de uma versão, só se acrescentam campos.
`deliveries[].payload.createdAt`	`string (date-time)`	Obrigatório.
`deliveries[].payload.data`	`object`	Obrigatório.
`deliveries[].payload.data.task`	`Task`
`deliveries[].payload.data.vehicle`	`any`	Um Vehicle; {id, name} nos eventos de zona.
`deliveries[].payload.data.zone`	`object`
`deliveries[].payload.data.at`	`string (date-time)`
`deliveries[].payload.data.position`	`object`
`deliveries[].payload.data.alert`	`AlertEvent`
`deliveries[].payload.data.changed`	`string[]`	task.updated: os campos que a edição alterou.

200 OK

{
  "deliveries": [
    {
      "id": "dlv_Qa71ZcR0mX",
      "event": "string",
      "status": "pending",
      "attempts": 0,
      "lastStatus": 0,
      "lastError": "string",
      "nextAttemptAt": "2026-10-15T09:00:00+01:00",
      "createdAt": "2026-10-15T09:00:00+01:00",
      "deliveredAt": "2026-10-15T09:00:00+01:00",
      "payload": {
        "id": "evt_9bQ2xLm0aZc4RwYeT7Kp",
        "type": "string",
        "version": "2026-10-16",
        "createdAt": "2026-10-15T09:00:00+01:00",
        "data": {
          "task": {},
          "vehicle": "string",
          "zone": {},
          "at": "2026-10-15T09:00:00+01:00",
          "position": {},
          "alert": {},
          "changed": []
        }
      }
    }
  ]
}

Erros

default Erro

Enviar de novo uma entrega agora (falhada, ou entregue e pretendida outra vez); as suas tentativas são mantidas

POST https://nways.ng/maps/v1/fleet/webhooks/{id}/deliveries/{deliveryId}/retry

Parâmetros

Nome	Onde	Tipo	Descrição
`id`	caminho	`string`	Obrigatório.
`deliveryId`	caminho	`string`	Obrigatório.

cURL

curl -X POST "https://nways.ng/maps/v1/fleet/webhooks/string/deliveries/string/retry" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/webhooks/string/deliveries/string/retry', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/fleet/webhooks/string/deliveries/string/retry",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Em fila

Campo	Tipo	Descrição
`id`	`string`	Obrigatório.
`status`	`any`	Obrigatório.

202 OK

{
  "id": "string",
  "status": "string"
}

Erros

default Erro

Um evento, enviado por POST para o seu endpoint

POST o endereço do seu endpoint

Cabeçalhos: X-NWays-Event (o tipo), X-NWays-Delivery (dlv_…, o mesmo nas novas tentativas), X-NWays-Signature: t=<unix seconds>,v1=<hex> em que v1 = HMAC-SHA256(secret, "<t>.<raw body>"). Verifique-a com o segredo do seu endpoint e recuse marcas temporais com mais de 5 minutos de diferença. Responda com qualquer 2xx em menos de 10 s; qualquer outra resposta é repetida após 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h e 12 h, e depois marcada como falhada. Os eventos podem chegar fora de ordem ou mais do que uma vez: use o id do evento e o estado da tarefa. Eventos: task.created, task.assigned, task.arriving, task.completed, task.failed (data.task, uma Task), vehicle.offline (data.vehicle, um Vehicle; uma vez por silêncio mais longo do que offlineAfterS), e zone.entered / zone.exited (data.zone {id, name}, data.vehicle {id, name}, data.at, data.position {lat, lng}).

Parâmetros

Nome	Onde	Tipo	Descrição
`X-NWays-Signature`	cabeçalho	`string`	Obrigatório.
`X-NWays-Event`	cabeçalho	`string`	Obrigatório. Um de: `task.created`, `task.assigned`, `task.arriving`, `task.completed`, `task.failed`, `vehicle.offline`, `zone.entered`, `zone.exited`, `asset.geofence_exit`, `asset.geofence_enter`, `asset.silent`, `asset.idle`, `asset.alert_resolved`, `connection.approved`, `connection.declined`, `connection.revoked`, `connection.ended`, `driver.availability_changed`, `dispatch.offered`, `dispatch.accepted`, `dispatch.declined`, `dispatch.expired`, `dispatch.withdrawn`, `task.started`, `delivery.rated`, `fleet.crash.detected`, `fleet.crash.resolved`, `task.updated`.
`X-NWays-Delivery`	cabeçalho	`string`	Obrigatório.

Corpo do pedido

Campo	Tipo	Descrição
`id`	`string`	Obrigatório.
`type`	`string`	Obrigatório. Um EventType, ou `ping` vindo da chamada de teste.
`version`	`string`	Obrigatório. A versão da forma do conteúdo: dentro de uma versão, só se acrescentam campos.
`createdAt`	`string (date-time)`	Obrigatório.
`data`	`object`	Obrigatório.
`data.task`	`Task`
`data.task.id`	`string`	Obrigatório.
`data.task.ref`	`string`	Obrigatório. O número curto da entrega no projeto, atribuído pela N-Ways ("1042", mostrado como #1042): para pessoas, em alertas e listas.
`data.task.status`	`string`	Obrigatório. Um de: `created`, `assigned`, `picked_up`, `arriving`, `completed`, `failed`, `cancelled`.
`data.task.vehicleId`	`string \| null`	Obrigatório.
`data.task.pickup`	`Stop \| null`	Obrigatório.
`data.task.dropoff`	`Stop`	Obrigatório.
`data.task.dropoff.lat`	`number`	Obrigatório.
`data.task.dropoff.lng`	`number`	Obrigatório.
`data.task.dropoff.name`	`string`	Até 120 caracteres.
`data.task.dropoff.address`	`string`	Até 300 caracteres.
`data.task.recipientName`	`string`	Obrigatório.
`data.task.recipientPhone`	`string`
`data.task.notes`	`string`	Obrigatório.
`data.task.lang`	`string`	Obrigatório. Um de: `en`, `fr`, `pt`.
`data.task.arrivingS`	`integer`	Obrigatório.
`data.task.eta`	`ETA \| null`	Obrigatório. Nulo até chegar uma posição recente, e depois de a tarefa terminar.
`data.task.dueAt`	`string (date-time) \| null`	Obrigatório.
`data.task.late`	`boolean`	Obrigatório. Em aberto e com dueAt ultrapassado, ou prevista para depois dele.
`data.task.trackingUrl`	`string (uri) \| null`	Obrigatório. Nulo depois de expirar.
`data.task.trackingExpiresAt`	`string (date-time) \| null`	Obrigatório.
`data.task.failureReason`	`string`
`data.task.createdAt`	`string (date-time)`	Obrigatório.
`data.task.assignedAt`	`string (date-time) \| null`	Obrigatório.
`data.task.pickedUpAt`	`string (date-time) \| null`	Obrigatório.
`data.task.arrivingAt`	`string (date-time) \| null`	Obrigatório.
`data.task.endedAt`	`string (date-time) \| null`	Obrigatório.
`data.task.area`	`Area \| null`	A área própria da entrega: sair dela gera asset.geofence_exit.
`data.task.proofs`	`Proof[]`	Apenas em GET /tasks/{id}: as fotografias e assinaturas do estafeta (N-Ways Business).
`data.task.proofs[].id`	`string`	Obrigatório.
`data.task.proofs[].kind`	`string`	Obrigatório. Um de: `photo`, `signature`.
`data.task.proofs[].contentType`	`string`	Obrigatório. Um de: `image/jpeg`, `image/png`, `image/webp`.
`data.task.proofs[].bytes`	`integer`	Obrigatório.
`data.task.proofs[].lat`	`number \| null`	Obrigatório.
`data.task.proofs[].lng`	`number \| null`	Obrigatório.
`data.task.proofs[].by`	`string`	Obrigatório. O nome do estafeta.
`data.task.proofs[].createdAt`	`string (date-time)`	Obrigatório.
`data.task.endNote`	`string`	Apenas em GET /tasks/{id}: o que o estafeta escreveu ao terminar.
`data.task.recipientEmail`	`string`
`data.task.proofRequired`	`string[]`	O da própria entrega, senão o das suas definições.
`data.task.proofRequiredOverride`	`string[] \| null`
`data.task.packageSize`	`string \| null`	Um de: `small`, `medium`, `large`, `null`.
`data.task.itemDescription`	`string`
`data.task.reference`	`string`
`data.task.scheduledAt`	`string (date-time) \| null`
`data.task.connectionId`	`string \| null`	A ligação do motorista N-Ways que a aceitou.
`data.task.acceptedAt`	`string (date-time) \| null`
`data.task.startedAt`	`string (date-time) \| null`
`data.task.editable`	`string`	O que PATCH /tasks/{id} pode alterar agora: tudo, apenas notes e dueAt (recolhida ou iniciada), ou nada (terminada). Um de: `all`, `limited`, `none`.
`data.task.editedAt`	`string (date-time) \| null`	A última edição.
`data.task.editedFields`	`string[]`	O que a última edição alterou.
`data.task.pinDelivery`	`PinDelivery`	Como o PIN de entrega está a chegar ao cliente, quando a entrega pede um e os PIN vão por WhatsApp. Nunca o próprio PIN.
`data.task.pinDelivery.channel`	`string`	Obrigatório. Um de: `whatsapp`, `email`, `none`.
`data.task.pinDelivery.state`	`string`	Obrigatório. Um de: `sending`, `sent`, `delivered`, `read`, `failed`.
`data.task.pinDelivery.whatsappErrorCode`	`integer \| null`	Obrigatório. A falha do WhatsApp (131026: não está no WhatsApp), guardada depois de o PIN ter ido por e-mail.
`data.task.pinDelivery.needsEmail`	`boolean`	Obrigatório. O cliente não recebeu o PIN: envie-o com POST /tasks/{id}/pin-email.
`data.task.pinDelivery.updatedAt`	`string (date-time)`	Obrigatório.
`data.vehicle`	`any`	Um Vehicle; {id, name} nos eventos de zona.
`data.zone`	`object`
`data.zone.id`	`string`
`data.zone.name`	`string`
`data.at`	`string (date-time)`
`data.position`	`object`
`data.position.lat`	`number`
`data.position.lng`	`number`
`data.alert`	`AlertEvent`
`data.alert.id`	`string`	Obrigatório.
`data.alert.ruleId`	`string`	Obrigatório. Um id de regra, ou default:dispatch para uma área de entrega sem regra própria, default:crash para um acidente sem regra de acidente.
`data.alert.ruleName`	`string`
`data.alert.kind`	`string`	Obrigatório. Um de: `geofence_exit`, `geofence_enter`, `silent`, `idle`, `crash`, `tracker_alarm`.
`data.alert.vehicleId`	`string`	Obrigatório.
`data.alert.vehicleName`	`string`
`data.alert.subject`	`string`	task:<id> ou zone:<id> para as geovedações; crash:<crs_id> para um acidente.
`data.alert.state`	`string`	Obrigatório. Um de: `open`, `acknowledged`, `resolved`.
`data.alert.detail`	`object`	Obrigatório. position, at, taskId, area, zoneId, zoneName, lastSeenAt, since…; um acidente: crashId, at, position, accuracyM, speedBeforeKmh, road, driverName, driverPhone (quando o tem), taskId, taskRef, taskLabel, state (help \| resolved), resolvedHow (ok \| help_here).
`data.alert.startedAt`	`string (date-time)`	Obrigatório.
`data.alert.notifiedAt`	`string (date-time) \| null`
`data.alert.notifications`	`integer`
`data.alert.acknowledgedBy`	`string`
`data.alert.acknowledgedAt`	`string (date-time) \| null`
`data.alert.resolvedBy`	`string`
`data.alert.resolvedAt`	`string (date-time) \| null`
`data.alert.autoResolved`	`boolean`	Resolvido por si (de volta ao interior, com sinal de novo, em movimento).
`data.changed`	`string[]`	task.updated: os campos que a edição alterou.

Exemplo

{
  "id": "evt_9bQ2xLm0aZc4RwYeT7Kp",
  "type": "string",
  "version": "2026-10-16",
  "createdAt": "2026-10-15T09:00:00+01:00",
  "data": {
    "task": {
      "id": "string",
      "ref": "string",
      "status": "created",
      "vehicleId": "string",
      "pickup": {
        "lat": 0,
        "lng": 0,
        "name": "string",
        "address": "string"
      },
      "dropoff": {
        "lat": 0,
        "lng": 0,
        "name": "string",
        "address": "string"
      },
      "recipientName": "string",
      "recipientPhone": "string",
      "notes": "string",
      "lang": "en",
      "arrivingS": 0,
      "eta": {
        "at": "2026-10-15T09:00:00+01:00",
        "durationS": 0,
        "distanceM": 0,
        "trafficDelayS": 0,
        "pickupAt": "2026-10-15T09:00:00+01:00",
        "updatedAt": "2026-10-15T09:00:00+01:00"
      },
      "dueAt": "2026-10-15T09:00:00+01:00",
      "late": true,
      "trackingUrl": "string",
      "trackingExpiresAt": "2026-10-15T09:00:00+01:00",
      "failureReason": "string",
      "createdAt": "2026-10-15T09:00:00+01:00",
      "assignedAt": "2026-10-15T09:00:00+01:00",
      "pickedUpAt": "2026-10-15T09:00:00+01:00",
      "arrivingAt": "2026-10-15T09:00:00+01:00",
      "endedAt": "2026-10-15T09:00:00+01:00",
      "area": {
        "type": "circle",
        "lat": 6.48,
        "lng": 3.43,
        "radiusM": 2500
      },
      "proofs": [
        {
          "id": "string",
          "kind": "photo",
          "contentType": "image/jpeg",
          "bytes": 0,
          "lat": 0,
          "lng": 0,
          "by": "string",
          "createdAt": "2026-10-15T09:00:00+01:00"
        }
      ],
      "endNote": "string",
      "recipientEmail": "string",
      "proofRequired": [
        "photo"
      ],
      "proofRequiredOverride": [
        "string"
      ],
      "packageSize": "small",
      "itemDescription": "string",
      "reference": "string",
      "scheduledAt": "2026-10-15T09:00:00+01:00",
      "connectionId": "string",
      "acceptedAt": "2026-10-15T09:00:00+01:00",
      "startedAt": "2026-10-15T09:00:00+01:00",
      "editable": "all",
      "editedAt": "2026-10-15T09:00:00+01:00",
      "editedFields": [
        "string"
      ],
      "pinDelivery": {
        "channel": "whatsapp",
        "state": "sending",
        "whatsappErrorCode": 0,
        "needsEmail": true,
        "updatedAt": "2026-10-15T09:00:00+01:00"
      }
    },
    "vehicle": "string",
    "zone": {
      "id": "string",
      "name": "string"
    },
    "at": "2026-10-15T09:00:00+01:00",
    "position": {
      "lat": 0,
      "lng": 0
    },
    "alert": {
      "id": "alr_8KwP2nVd5T",
      "ruleId": "string",
      "ruleName": "string",
      "kind": "geofence_exit",
      "vehicleId": "string",
      "vehicleName": "string",
      "subject": "string",
      "state": "open",
      "detail": {},
      "startedAt": "2026-10-15T09:00:00+01:00",
      "notifiedAt": "2026-10-15T09:00:00+01:00",
      "notifications": 0,
      "acknowledgedBy": "string",
      "acknowledgedAt": "2026-10-15T09:00:00+01:00",
      "resolvedBy": "string",
      "resolvedAt": "2026-10-15T09:00:00+01:00",
      "autoResolved": true
    },
    "changed": [
      "string"
    ]
  }
}

Resposta

Recebido

Webhooks

Listar endpoints de webhook

Resposta

Erros

Adicionar um endpoint (até 10); a resposta traz o seu segredo de assinatura, mostrado uma única vez

Corpo do pedido

Resposta

Erros

Alterar o url, os eventos ou o active de um endpoint

Parâmetros

Corpo do pedido

Resposta

Erros

Eliminar um endpoint e o seu registo de entregas

Parâmetros

Resposta

Erros

Um novo segredo de assinatura (mostrado uma única vez); o antigo deixa de funcionar de imediato

Parâmetros

Resposta

Erros

Pôr em fila um evento ping para o endpoint

Parâmetros

Resposta

Erros

O registo de entregas do endpoint, das mais recentes para as mais antigas (guardado 30 dias)

Parâmetros

Resposta

Erros

Enviar de novo uma entrega agora (falhada, ou entregue e pretendida outra vez); as suas tentativas são mantidas

Parâmetros

Resposta

Erros

Um evento, enviado por POST para o seu endpoint

Parâmetros

Corpo do pedido

Resposta

Pôr em fila um evento `ping` para o endpoint