Abrir NextChat
Endpoints

Referência: webhooks

Cadastrar, editar, testar e acompanhar os webhooks.

Nesta página

Todos os exemplos de resposta foram gerados chamando a API de verdade. Os caminhos são relativos à base URL e toda chamada leva Authorization: Bearer nck_….

Base URLhttps://app.nextchat.nextsistem.dev.br/api/integrations/v1

Como receber e conferir os avisos: Webhooks. O JSON de cada evento: Eventos do webhook.

Listar webhooks

GET /integrations/webhooks Permissão webhooks:manage

Exemplo de chamada

GET/integrations/webhooksbash
curl -X GET "$NEXTCHAT_API/integrations/webhooks" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 200 · Sucesso

Resposta 200json
[
  {
    "id": "10c3cec1-77a1-461a-ae66-b2f16c406083",
    "name": "ERP da loja",
    "url": "https://erp.exemplo.com.br/nextchat/webhook",
    "events": [
      "message.received",
      "attendance.closed"
    ],
    "active": true,
    "consecutive_failures": 0,
    "last_status": null,
    "last_error": "",
    "last_delivery_at": null,
    "created_at": "2026-10-22T22:26:56.537348-03:00",
    "auth_kind": "none",
    "auth_header": "",
    "auth_hint": ""
  }
]

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

Cadastrar webhook (devolve o segredo uma vez)

POST /integrations/webhooks Permissão webhooks:manage

Cadastra um endereço https que recebe os eventos. O segredo whsec_ da assinatura vem uma única vez. Se o seu sistema exige login, informe auth_kind (bearer ou header) e auth_value: o token vai em cada entrega, junto com a assinatura. O formato de cada evento está em /docs/api/webhooks-eventos: mensagens trazem contact e channel, e mensagens com arquivo só são avisadas quando o arquivo está pronto (media_id e media.url, link de 15 minutos).

Corpo (JSON)

CampoTipoDescrição
name obrigatóriotextoNome para reconhecer o endereço.
url obrigatóriotextoEndereço https público que recebe o POST.
events obrigatóriolistaEventos que este endereço recebe (GET /integrations/webhooks/events). · lista de string
auth_kindtextoAutenticação no destino, além da assinatura: none (só a assinatura), bearer (vai em Authorization: Bearer <auth_value>) ou header (vai em <auth_header>: <auth_value>). · none, bearer, header
auth_headertextoNome do cabeçalho quando auth_kind é header (ex.: X-Api-Key). Não pode ser um cabeçalho do envio nem começar com X-NextChat-.
auth_valuetextoO token ou a chave que o destino exige. Nunca volta nas respostas (só auth_hint, o fim dele). Na edição, vazio com o mesmo auth_kind mantém o guardado.

Exemplo de chamada

POST/integrations/webhooksbash
curl -X POST "$NEXTCHAT_API/integrations/webhooks" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":["message.received","attendance.closed"],"name":"ERP da loja","url":"https://erp.exemplo.com.br/nextchat/webhook"}'

Resposta 201 · Criado

Resposta 201json
{
  "endpoint": {
    "id": "10c3cec1-77a1-461a-ae66-b2f16c406083",
    "name": "ERP da loja",
    "url": "https://erp.exemplo.com.br/nextchat/webhook",
    "events": [
      "message.received",
      "attendance.closed"
    ],
    "active": true,
    "consecutive_failures": 0,
    "last_status": null,
    "last_error": "",
    "last_delivery_at": null,
    "created_at": "2026-10-22T22:26:56.537348-03:00",
    "auth_kind": "none",
    "auth_header": "",
    "auth_hint": ""
  },
  "secret": "whsec_6vQm2Xc9…"
}

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

Eventos disponíveis

GET /integrations/webhooks/events Permissão webhooks:manage

Exemplo de chamada

GET/integrations/webhooks/eventsbash
curl -X GET "$NEXTCHAT_API/integrations/webhooks/events" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 200 · Sucesso

Resposta 200json
[
  "message.received",
  "message.sent",
  "conversation.updated",
  "attendance.opened",
  "attendance.closed",
  "kanban.card.created",
  "kanban.card.moved",
  "kanban.card.completed"
]

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

Editar ou reativar webhook

PATCH /integrations/webhooks/{id} Permissão webhooks:manage

Edita nome, endereço, eventos, ativação e a autenticação no destino. auth_kind none tira a autenticação; com o mesmo auth_kind e sem auth_value, o token guardado é mantido.

Parâmetros do caminho

ParâmetroTipoDescrição
id obrigatórioUUIDIdentificador (UUID)

Corpo (JSON)

CampoTipoDescrição
nametextoNome.
urltextoEndereço https.
eventslistaEventos (a lista substitui a atual). · lista de string
activesim/nãotrue reativa um endereço desativado por falhas; false pausa.
auth_kindtextoAutenticação no destino, além da assinatura: none (só a assinatura), bearer (vai em Authorization: Bearer <auth_value>) ou header (vai em <auth_header>: <auth_value>). · none, bearer, header
auth_headertextoNome do cabeçalho quando auth_kind é header (ex.: X-Api-Key). Não pode ser um cabeçalho do envio nem começar com X-NextChat-.
auth_valuetextoO token ou a chave que o destino exige. Nunca volta nas respostas (só auth_hint, o fim dele). Na edição, vazio com o mesmo auth_kind mantém o guardado.

Exemplo de chamada

PATCH/integrations/webhooks/{id}bash
curl -X PATCH "$NEXTCHAT_API/integrations/webhooks/{id}" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth_kind":"bearer","auth_value":"token-do-erp","events":["message.received","message.sent","attendance.closed"]}'

Resposta 200 · Sucesso

Resposta 200json
{
  "id": "10c3cec1-77a1-461a-ae66-b2f16c406083",
  "name": "ERP da loja",
  "url": "https://erp.exemplo.com.br/nextchat/webhook",
  "events": [
    "message.received",
    "message.sent",
    "attendance.closed"
  ],
  "active": true,
  "consecutive_failures": 0,
  "last_status": null,
  "last_error": "",
  "last_delivery_at": null,
  "created_at": "2026-10-22T22:26:56.537348-03:00",
  "auth_kind": "bearer",
  "auth_header": "Authorization",
  "auth_hint": "••••-erp"
}

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

Apagar webhook

DELETE /integrations/webhooks/{id} Permissão webhooks:manage

Parâmetros do caminho

ParâmetroTipoDescrição
id obrigatórioUUIDIdentificador (UUID)

Exemplo de chamada

DELETE/integrations/webhooks/{id}bash
curl -X DELETE "$NEXTCHAT_API/integrations/webhooks/{id}" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 204 · Sucesso, sem corpo de resposta

Sem corpo de resposta.

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

Redefinir o segredo de assinatura

POST /integrations/webhooks/{id}/rotate-secret Permissão webhooks:manage

Parâmetros do caminho

ParâmetroTipoDescrição
id obrigatórioUUIDIdentificador (UUID)

Exemplo de chamada

POST/integrations/webhooks/{id}/rotate-secretbash
curl -X POST "$NEXTCHAT_API/integrations/webhooks/{id}/rotate-secret" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 200 · Sucesso

Resposta 200json
{
  "endpoint": {
    "id": "10c3cec1-77a1-461a-ae66-b2f16c406083",
    "name": "ERP da loja",
    "url": "https://erp.exemplo.com.br/nextchat/webhook",
    "events": [
      "message.received",
      "message.sent",
      "attendance.closed"
    ],
    "active": true,
    "consecutive_failures": 0,
    "last_status": null,
    "last_error": "",
    "last_delivery_at": null,
    "created_at": "2026-10-22T22:26:56.537348-03:00",
    "auth_kind": "bearer",
    "auth_header": "Authorization",
    "auth_hint": "••••-erp"
  },
  "secret": "whsec_6vQm2Xc9…"
}

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

Enviar evento de teste

POST /integrations/webhooks/{id}/test Permissão webhooks:manage

Parâmetros do caminho

ParâmetroTipoDescrição
id obrigatórioUUIDIdentificador (UUID)

Exemplo de chamada

POST/integrations/webhooks/{id}/testbash
curl -X POST "$NEXTCHAT_API/integrations/webhooks/{id}/test" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 200 · Sucesso

Resposta 200json
{
  "error": "",
  "ok": true,
  "status": 200
}

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

Últimas entregas

GET /integrations/webhooks/{id}/deliveries Permissão webhooks:manage

Parâmetros do caminho

ParâmetroTipoDescrição
id obrigatórioUUIDIdentificador (UUID)

Exemplo de chamada

GET/integrations/webhooks/{id}/deliveriesbash
curl -X GET "$NEXTCHAT_API/integrations/webhooks/{id}/deliveries" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 200 · Sucesso

Resposta 200json
[
  {
    "id": "9b2f6c1e-4a7d-4e3b-8f21-6d5c4b3a2f10",
    "event": "message.received",
    "status": "done",
    "attempts": 1,
    "last_status": 200,
    "last_error": "",
    "created_at": "2026-10-23T10:05:11.06-03:00",
    "delivered_at": "2026-10-23T10:05:11.31-03:00",
    "next_at": "2026-10-23T10:05:11.06-03:00"
  },
  {
    "id": "1c8e5d2a-7b3f-4c9e-a0d4-2e6f8a1b3c57",
    "event": "attendance.closed",
    "status": "pending",
    "attempts": 2,
    "last_status": 503,
    "last_error": "resposta 503",
    "created_at": "2026-10-23T10:20:57.67-03:00",
    "delivered_at": null,
    "next_at": "2026-10-23T10:23:28-03:00"
  }
]

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

↑ ↓ navegar↵ abrirEsc fechar