Webhooks — Referência da API

GET /webhooks webhooks:manage

Listar webhooks

Webhooks da conta (até 5). O segredo não aparece aqui.

Exemplo

cURL

curl -X GET "https://leadgo.com.br/api/v1/webhooks" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": [
        {
            "id": "01jbz8e2h6k0n4r8u2x6b0f4jm",
            "url": "https://erp.loja.exemplo.com.br/hooks/leadgo",
            "description": "ERP",
            "events": [
                "campaign.published",
                "campaign.failed",
                "campaign.status_changed"
            ],
            "is_active": true,
            "failure_count": 0,
            "last_error": null,
            "last_delivered_at": "2026-10-28T15:10:00+00:00",
            "created_at": "2026-10-28T15:00:00+00:00"
        }
    ]
}

POST /webhooks webhooks:manage

Criar webhook

A URL https pública que recebe os avisos. O segredo para conferir a assinatura vem só nesta resposta (secret). Sem events, assina todos.

Corpo

url obrigatório	string	URL https pública (sem redirecionamento).
description	string	Para reconhecer na lista.
events	string[]	campaign.published, campaign.failed, campaign.status_changed, campaign.deleted, ad.approved, ad.rejected, alert.created, ad_account.status_changed, lead.created, lead.status_changed, lead.scored, brain.report_ready, media.ready, media.failed. Sem o campo, todos os que quem criou o token pode assinar: os lead.* pedem a permissão de ver leads e o brain.report_ready a de ver o Gestor IA.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/webhooks" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.loja.exemplo.com.br/hooks/leadgo",
    "description": "ERP",
    "events": [
        "campaign.published",
        "campaign.failed",
        "campaign.status_changed"
    ]
}'

Resposta 201

HTTP 201

{
    "data": {
        "id": "01jbz8e2h6k0n4r8u2x6b0f4jm",
        "url": "https://erp.loja.exemplo.com.br/hooks/leadgo",
        "description": "ERP",
        "events": [
            "campaign.published",
            "campaign.failed",
            "campaign.status_changed"
        ],
        "is_active": true,
        "failure_count": 0,
        "last_error": null,
        "last_delivered_at": null,
        "created_at": "2026-10-28T15:00:00+00:00",
        "secret": "whsec_8hJ2kL9mN3pQ5rS7tV1wX4yZ6aB0cD2eF4gH6jK8"
    }
}

Erros: validation_failed, webhook_limit_reached

GET /webhooks/{id} webhooks:manage

Consultar webhook

Um webhook, com a última entrega e o último erro.

Exemplo

cURL

curl -X GET "https://leadgo.com.br/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": {
        "id": "01jbz8e2h6k0n4r8u2x6b0f4jm",
        "url": "https://erp.loja.exemplo.com.br/hooks/leadgo",
        "description": "ERP",
        "events": [
            "campaign.published",
            "campaign.failed",
            "campaign.status_changed"
        ],
        "is_active": true,
        "failure_count": 0,
        "last_error": null,
        "last_delivered_at": "2026-10-28T15:10:00+00:00",
        "created_at": "2026-10-28T15:00:00+00:00"
    }
}

Erros: not_found

PATCH /webhooks/{id} webhooks:manage

Alterar webhook

URL, eventos, ligar/desligar (is_active) e troca do segredo (rotate_secret: o novo vem só nesta resposta). Religar zera a contagem de falhas.

Corpo

url	string	Nova URL.
description	string	Nova descrição.
events	string[]	Eventos assinados.
is_active	boolean	Liga ou desliga os avisos.
rotate_secret	boolean	Gera um segredo novo.

Exemplo

cURL

curl -X PATCH "https://leadgo.com.br/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": true,
    "rotate_secret": true
}'

Resposta 200

HTTP 200

{
    "data": {
        "id": "01jbz8e2h6k0n4r8u2x6b0f4jm",
        "url": "https://erp.loja.exemplo.com.br/hooks/leadgo",
        "description": "ERP",
        "events": [
            "campaign.published",
            "campaign.failed",
            "campaign.status_changed"
        ],
        "is_active": true,
        "failure_count": 0,
        "last_error": null,
        "last_delivered_at": "2026-10-28T15:10:00+00:00",
        "created_at": "2026-10-28T15:00:00+00:00",
        "secret": "whsec_3nM5pQ7rS9tV1wX3yZ5aB7cD9eF1gH3jK5mN7pQ9"
    }
}

Erros: validation_failed, not_found

DELETE /webhooks/{id} webhooks:manage

Excluir webhook

Os avisos para esta URL param na hora.

Exemplo

cURL

curl -X DELETE "https://leadgo.com.br/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 204

Sem corpo.

Erros: not_found

POST /webhooks/{id}/test webhooks:manage

Testar webhook

Envia agora um aviso webhook.test, assinado, e diz o que a URL respondeu. Não conta para desligar o webhook.

Exemplo

cURL

curl -X POST "https://leadgo.com.br/api/v1/webhooks/{id}/test" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": {
        "delivered": true,
        "status": 200,
        "error": null,
        "event_id": "evt_01jbz9a1c5f9j3m7q1t5x9b3e7"
    }
}

Erros: not_found