Webhooks

Webhooks permitem que sua aplicação receba notificações em tempo real quando eventos ocorrem no eAgenda, sem precisar ficar consultando a API periodicamente.

Como funcionam

1. Você cadastra uma URL de callback no eAgenda
2. Quando um evento ocorre (ex: novo agendamento), o eAgenda envia um POST para sua URL
3. Sua aplicação processa a notificação e responde com status 200

Gerenciar webhooks via API

Listar webhooks

curl -X GET "https://eagenda.com.br/api/v3/webhooks/" \
  -H "Authorization: Basic SEU_TOKEN"

Criar um webhook

curl -X POST "https://eagenda.com.br/api/v3/webhooks/" \
  -H "Authorization: Basic SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com/webhook/eagenda",
    "events": ["appointment.created", "appointment.canceled"]
  }'

Atualizar um webhook

curl -X PUT "https://eagenda.com.br/api/v3/webhooks/WEBHOOK_KEY/" \
  -H "Authorization: Basic SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com/webhook/eagenda-v2",
    "events": ["appointment.created", "appointment.canceled", "appointment.updated"]
  }'

Excluir um webhook

curl -X DELETE "https://eagenda.com.br/api/v3/webhooks/WEBHOOK_KEY/" \
  -H "Authorization: Basic SEU_TOKEN"

Configurar via painel

Você também pode configurar webhooks pelo painel do eAgenda:

1. Acesse Configurações > Integrações > Webhooks
2. Clique em Adicionar Webhook
3. Informe a URL de callback e selecione os eventos desejados
4. Clique em Salvar

Recebendo notificações

Quando um evento ocorre, o eAgenda envia um POST para sua URL com os dados do evento no corpo da requisição em formato JSON.

Exemplo de payload

{
  "event": "appointment.created",
  "timestamp": "2026-06-04T14:30:00-03:00",
  "data": {
    "appointment_key": "apt12345-1234-5678-9abc-def012345678",
    "search_code": "AGD-2026-001234",
    "status": "CONFIRMED",
    "start_date": "2026-06-10T09:00:00-03:00",
    "calendar": {
      "calendar_key": "abc12345-...",
      "name": "Consultório Dr. Silva"
    },
    "person": {
      "full_name": "João da Silva",
      "email": "joao@exemplo.com"
    }
  }
}

Exemplo de servidor para receber webhooks

Python (Flask):

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhook/eagenda", methods=["POST"])
def handle_webhook():
    payload = request.json
    event = payload.get("event")

    if event == "appointment.created":
        print(f"Novo agendamento: {payload['data']['search_code']}")
        # Sua lógica aqui (ex: enviar SMS, atualizar CRM)

    elif event == "appointment.canceled":
        print(f"Cancelamento: {payload['data']['search_code']}")
        # Sua lógica aqui

    return jsonify({"status": "ok"}), 200

if __name__ == "__main__":
    app.run(port=5000)

Node.js (Express):

const express = require("express");
const app = express();
app.use(express.json());

app.post("/webhook/eagenda", (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case "appointment.created":
      console.log(`Novo agendamento: ${data.search_code}`);
      // Sua lógica aqui
      break;
    case "appointment.canceled":
      console.log(`Cancelamento: ${data.search_code}`);
      break;
  }

  res.status(200).json({ status: "ok" });
});

app.listen(5000, () => console.log("Webhook server running on port 5000"));

Boas práticas

1. Responda rapidamente — Retorne 200 o mais rápido possível. Processe a lógica pesada em background
2. Idempotência — Sua aplicação pode receber o mesmo evento mais de uma vez. Use o appointment_key para verificar duplicatas
3. HTTPS obrigatório — Use sempre HTTPS na URL do webhook
4. Logs — Registre todas as notificações recebidas para debugging
5. Retry — Se sua aplicação retornar erro (status != 2xx), o eAgenda pode tentar reenviar a notificação
6. Validação — Valide o conteúdo recebido antes de processar