API — Webhooks (gerenciar)

Esta página cobre os endpoints que gerenciam a configuração do webhook. Para entender como ele funciona na prática — payload, entrega, segurança —, veja a seção Webhooks.

Endpoints

Método	Endpoint	Ação
`GET`	`/api/v1/accounts/{id}/webhooks`	Lista os webhooks da conta
`POST`	`/api/v1/accounts/{id}/webhooks`	Cria webhook
`PATCH`	`/api/v1/accounts/{id}/webhooks/{webhook_id}`	Atualiza URL, nome ou eventos
`DELETE`	`/api/v1/accounts/{id}/webhooks/{webhook_id}`	Remove

São esses quatro. Não existe GET de um webhook específico nem endpoint de teste — para ver um, liste todos e filtre pelo id.

Campos do recurso

{
  "id": 5,
  "name": "Integração ERP",
  "url": "https://seusistema.com.br/webhooks/smart?k=...",
  "subscriptions": [
    "conversation_created",
    "message_created",
    "contact_updated"
  ],
  "webhook_type": "account_type",
  "inbox_id": null,
  "account_id": 1
}

Campo	O que é
`name`	Rótulo seu, aparece na lista da tela
`url`	O endereço chamado. Único dentro da conta
`subscriptions`	Lista de eventos. Só aceita nomes de eventos válidos
`webhook_type`	`account_type` (o normal) ou `inbox_type`
`inbox_id`	Preenchido apenas em webhook de caixa

POST /webhooks

curl -X POST "https://app.smart2.com.br/api/v1/accounts/1/webhooks" \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusistema.com.br/webhooks/smart?k=um-valor-longo-e-aleatorio",
    "name": "Integração ERP",
    "subscriptions": [
      "conversation_created",
      "message_created",
      "conversion_event_created"
    ]
  }'

Regras de validação que derrubam o cadastro:

URL repetida na conta — o endereço é único
Endereço privado — localhost, 10.x, 172.16–31.x, 192.168.x, link-local e equivalentes IPv6 são recusados
Evento inválido — qualquer nome fora da lista de treze invalida a chamada inteira
Lista vazia — subscriptions precisa ter ao menos um evento

Os três eventos que só entram por aqui

O formulário da tela mostra dez opções. Estes três o backend aceita e a tela não oferece:

inbox_created
inbox_updated
conversion_event_created

O último é o mais útil de todos para integração de marketing — é ele que avisa na hora que entrou lead novo, com a origem junto. Cadastre pela API:

curl -X POST "https://app.smart2.com.br/api/v1/accounts/1/webhooks" \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusistema.com.br/webhooks/leads?k=segredo",
    "name": "Leads para o BI",
    "subscriptions": ["conversion_event_created"]
  }'

PATCH /webhooks/{webhook_id}

curl -X PATCH "https://app.smart2.com.br/api/v1/accounts/1/webhooks/5" \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptions": ["conversation_created", "message_created"]
  }'

A lista de subscriptions é substituída, não somada. Para adicionar um evento, mande a lista completa com ele dentro.

Não há como pausar: como não existe campo enabled, parar de receber é remover o webhook.

DELETE /webhooks/{webhook_id}

curl -X DELETE "https://app.smart2.com.br/api/v1/accounts/1/webhooks/5" \
  -H "api_access_token: SEU_TOKEN"

Remove em definitivo.

Casos de uso

Cadastro inicial

webhook = requests.post(f"{BASE_URL}/webhooks", headers=HEADERS, json={
    "url": "https://seusistema.com.br/webhooks/smart?k=SEGREDO",
    "name": "Integração ERP",
    "subscriptions": [
        "conversation_created",
        "conversation_status_changed",
        "message_created",
        "contact_created",
        "contact_updated",
        "conversion_event_created",
    ],
}).json()

print(webhook["id"])

Trocar o endereço depois de migrar de servidor

webhooks = requests.get(f"{BASE_URL}/webhooks", headers=HEADERS).json()
antigo = next(w for w in webhooks if "servidor-antigo.com" in w["url"])

requests.patch(f"{BASE_URL}/webhooks/{antigo['id']}", headers=HEADERS, json={
    "url": "https://servidor-novo.com.br/webhooks/smart?k=SEGREDO"
})

Separar por finalidade

A URL é única na conta, então cada sistema usa o seu caminho:

requests.post(f"{BASE_URL}/webhooks", headers=HEADERS, json={
    "url": "https://erp.empresa.com/webhooks/smart",
    "name": "ERP",
    "subscriptions": ["contact_created", "contact_updated"],
})

requests.post(f"{BASE_URL}/webhooks", headers=HEADERS, json={
    "url": "https://bi.empresa.com/webhooks/smart",
    "name": "BI",
    "subscriptions": ["conversion_event_created", "conversation_created"],
})

Reagir a negócio

Não tem por aqui. Nenhum evento de funil existe no webhook da conta — negócio criado, movido, ganho ou perdido não disparam nada aqui. O caminho é a automação do funil, com ação de enviar webhook. Veja eventos disponíveis.