Webhooks

Configure webhooks para receber notificações HTTP em tempo real quando eventos ocorrem.

Para guia detalhado de implementação, veja o Guia de Webhooks.

Permissão de administrador

Listar, criar, atualizar e remover webhooks exige um token de usuário com perfil administrador na conta. Tokens de agentes não podem gerenciar estes endpoints.

GET/api/v1/accounts/{account_id}/webhooks

Lista todos os webhooks configurados na conta.

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/webhooks" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Lista de webhooks (aninhada em payload.webhooks)

json

{
  "payload": {
    "webhooks": [
      {
        "id": 1,
        "name": "Integração principal",
        "account_id": 1,
        "url": "https://meuapp.com/webhooks/chat",
        "subscriptions": [
          "conversation_created",
          "message_created",
          "contact_created"
        ],
        "secret": "<segredo HMAC>"
      }
    ]
  }
}

POST/api/v1/accounts/{account_id}/webhooks

Registra um novo webhook para receber eventos.

Body (envolto em objeto webhook)

Nome	Tipo	Obrigatorio	Descricao
`url`	`string`	Sim	URL HTTP ou HTTPS que receberá os eventos via POST. Em produção, prefira HTTPS.
`subscriptions`	`array[string] \| null`	Nao	Lista não vazia de eventos. Na criação, omitir ou enviar null usa os oito eventos padrão; [] ou valores fora do catálogo retornam 422.
`name`	`string`	Nao	Nome descritivo do webhook
`inbox_id`	`integer`	Nao	Associa uma inbox ao registro. Neste endpoint, não altera webhook_type nem filtra a entrega por inbox.

Wrapper do contrato

Envie os campos do webhook dentro de um objeto webhook: { "webhook": { "url": "...", "subscriptions": [...] } }.

Subscriptions padrão quando omitidas

Sem subscriptions, o registro nasce com conversation_status_changed, conversation_updated, conversation_created, contact_created, contact_updated, message_created, message_updated e webwidget_triggered.

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/webhooks" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "url": "https://meuapp.com/webhooks/noovichat",
      "subscriptions": [
        "conversation_created",
        "conversation_status_changed",
        "message_created",
        "contact_created"
      ]
    }
  }'

200Webhook criado (aninhado em payload.webhook; inclui name, account_id e secret)

json

{
  "payload": {
    "webhook": {
      "id": 2,
      "name": null,
      "account_id": 1,
      "url": "https://meuapp.com/webhooks/noovichat",
      "subscriptions": ["conversation_created", "message_created"],
      "secret": "<segredo usado para verificar a assinatura HMAC>"
    }
  }
}

404inbox_id não existe na conta autenticada ou pertence a outra conta.

422Objeto webhook malformado, URL inválida, subscriptions vazia, desconhecida ou fora de array[string], ou inbox_id malformado.

PATCH/api/v1/accounts/{account_id}/webhooks/{webhook_id}

Atualiza os campos permitidos de um webhook.

Body (webhook)

Nome	Tipo	Obrigatorio	Descricao
`url`	`string`	Nao	Nova URL do webhook
`subscriptions`	`array[string] \| null`	Nao	Nova lista não vazia de eventos. null é ignorado e preserva a lista atual; sem outro campo permitido, a atualização fica vazia e retorna 422.
`name`	`string`	Nao	Novo nome descritivo
`inbox_id`	`integer`	Nao	Inbox associada como metadado; não torna a entrega inbox-scoped

bash

curl -X PATCH "https://chat.seudominio.com/api/v1/accounts/1/webhooks/2" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "subscriptions": [
        "conversation_created",
        "message_created",
        "contact_updated"
      ]
    }
  }'

200Webhook atualizado, envolto em { payload: { webhook: { ... } } }.

404webhook_id não existe na conta, ou inbox_id não existe na conta autenticada ou pertence a outra conta.

422Atualização vazia, campo malformado, URL inválida ou subscriptions vazia, desconhecida ou fora de array[string].

DELETE/api/v1/accounts/{account_id}/webhooks/{webhook_id}

Remove um webhook. Eventos não serão mais enviados para a URL.

bash

curl -X DELETE "https://chat.seudominio.com/api/v1/accounts/1/webhooks/2" \
  -H "api_access_token: YOUR_TOKEN"

200Webhook removido; resposta sem corpo.

Eventos Disponíveis

O catálogo abaixo contém os 32 valores aceitos em subscriptions.

Evento	Descrição
`conversation_created`	Nova conversa criada
`conversation_updated`	Conversa atualizada
`conversation_status_changed`	Status da conversa alterado
`conversation_typing_on`	Indicador de digitação iniciado
`conversation_typing_off`	Indicador de digitação encerrado
`message_created`	Nova mensagem recebida ou enviada
`message_updated`	Mensagem atualizada
`contact_created`	Novo contato criado
`contact_updated`	Dados do contato atualizados
`webwidget_triggered`	Widget de chat acionado no site
`inbox_created`	Nova inbox criada
`inbox_updated`	Inbox atualizada
`broadcast_started`	Disparo em massa iniciado
`broadcast_completed`	Disparo em massa concluído

Payload do Webhook

Cada evento envia um payload JSON com os dados do evento. O campo event identifica o tipo de evento. Veja exemplos no Guia de Webhooks.

Eventos de Atendimentos

Disponível em toda licença NooviChat válida quando Atendimentos está configurado na conta.

Evento (campo event no payload)	Descrição
`appointment.created`	Novo atendimento agendado
`appointment.updated`	Dados do atendimento atualizados
`appointment.confirmed`	Atendimento confirmado
`appointment.completed`	Atendimento marcado como realizado
`appointment.cancelled`	Atendimento cancelado
`appointment.no_show`	Cliente não compareceu
`appointment.rescheduled`	Reagendamento realizado
`reminder.sent`	Lembrete enviado com sucesso
`reminder.failed`	Falha no envio do lembrete
`professional.created`	Profissional criado
`professional.updated`	Profissional atualizado
`service.created`	Serviço criado
`service.updated`	Serviço atualizado
`follow_up_scheduled`	Follow-up agendado
`follow_up_sent`	Mensagem de follow-up enviada
`follow_up_failed`	Falha no envio do follow-up
`follow_up_cancelled`	Follow-up cancelado
`broadcast_follow_up_sent`	Follow-up de disparo em massa enviado a quem não respondeu

Nomes canônicos e compatibilidade

Use os nomes com ponto mostrados na tabela tanto em subscriptions quanto ao interpretar o campo evententregue. As grafias antigas com sublinhado ainda são aceitas em subscriptions apenas para retrocompatibilidade, mas a entrega é normalizada para a grafia canônica com ponto. Os eventos de follow-up e broadcast permanecem com sublinhado. Não existem eventos de exclusão de profissional ou serviço.

Payloads de Lembrete

Os eventos reminder.sent e reminder.failed são entregues com um payload simples (campos diretos, sem objetos aninhados).

Payload — reminder.sent

json

{
  "event": "reminder.sent",
  "account_id": 1,
  "reminder_id": 88,
  "appointment_id": 42,
  "sent_at": "2026-06-14T10:00:00.000Z"
}

Payload — reminder.failed

json

{
  "event": "reminder.failed",
  "account_id": 1,
  "reminder_id": 88,
  "appointment_id": 42,
  "last_error": "Numero invalido ou fora de cobertura"
}