Webhook de Eventos - Maestro Docs

Os webhooks permitem que o Maestro envie notificações em tempo real para uma URL definida pelo cliente, sempre que determinados eventos ocorrerem. Assim, sua aplicação pode reagir automaticamente sem depender de consultas periódicas à API.

Criando um Webhook

Acesse Configurações > Empresa e role até a opção “Webhook”.
Clique em Adicionar Webhook.
Insira a URL de acesso da sua aplicação, responsável por receber os eventos — por exemplo: https://meuservidor.com/webhook/maestro.
(Opcional) Adicione headers personalizados para autenticação ou identificação, no formato Chave/Valor — por exemplo: Authorization / Bearer SEU_TOKEN_AQUI.

Estrutura de Requisição

Quando um evento é disparado, o Maestro envia uma requisição HTTP POST para a URL configurada. Atualmente, o único evento enviado é:

Atualização do status de mensagens

Atualização do status de mensagens

{
    "event_id": "01998719-3597-77dd-9a8f-40779b001e17",
    "category": "message",
    "type": "message_status",
    "timestamp": "2025-09-26T17:36:40.34399Z",
    "details": {
        "message_id": "01998718-d71d-7e7a-b1cd-0004ea177487",
        "company": {
            "id": "01950065-a1ec-75f1-a253-75458b2e10d1",
            "description": "Assessoria Global"
        },
        "channel": {
            "id": 2,
            "description": "Sms",
            "source": null
        },
        "contact": {
            "contract_code": "CTX0008",
            "document_number": "20329332090",
            "raw_phone_number": "5515981700308"
        },
        "segment": {
            "id": "019986ba-a006-71ce-b51f-46cf9ccab831",
            "description": "Segmento_Teste"
        },
        "status": {
            "id": 3,
            "description": "Delivered",
            "timestamp": "0001-01-01T00:00:00",
            "reason": null
        },
        "campaign": {
            "id": "01998718-cb08-78ca-bb65-8e536e21416f",
            "description": "multicanal_20250925_1440"
        },
        "template": {
            "id": "019986ba-a006-71ce-b51f-46cf9ccab831",
            "description": "smsMulticanal",
            "code": "S5499"
        },
        "provider": {
            "id": 1,
            "description": "Pontal",
            "details": {
                "type": "api_message",
                "id": "8175123191",
                "to": "15981700308",
                "message": "Ola Lucas Vizza 01! Somos a Robbu em parceria com BV.",
                "schedule": "2025-09-26T17:36:16Z",
                "reference": null,
                "vars": null,
                "status": "2",
                "statusDescription": "Queued"
            }
        },
        "custom_fields": null
    }
}

Objetos

Objeto	Descrição
`details.channel.id`	`1` - Email · `2` - SMS · `3` - Whatsapp
`details.status.id`	`1` - Queued · `2` - Sent · `3` - Delivered · `4` - Failed · `5` - Read

O evento traz também details.provider.details.status — este é o status bruto retornado pelo provedor (broker), específico de cada integração, e não deve ser confundido com details.status.id (o status normalizado do Maestro).

Não está recebendo eventos no seu endpoint? Veja Troubleshooting.