Webhooks

Webhooks allow your application to receive real-time notifications when events occur in eAgenda, without needing to poll the API constantly.

How they work

1. You register a callback URL in eAgenda
2. When an event occurs (e.g., new appointment), eAgenda sends a POST to your URL
3. Your application processes the notification and responds with status 200

Manage webhooks via API

List webhooks

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

Create a webhook

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

Update a webhook

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

Delete a webhook

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

Configure via dashboard

You can also configure webhooks through the eAgenda dashboard:

1. Go to Settings > Integrations > Webhooks
2. Click Add Webhook
3. Enter the callback URL and select the desired events
4. Click Save

Receiving notifications

When an event occurs, eAgenda sends a POST to your URL with the event data in the request body as JSON.

Example 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": "Dr. Silva's Office"
    },
    "person": {
      "full_name": "John Smith",
      "email": "john@example.com"
    }
  }
}

Example webhook server

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"New appointment: {payload['data']['search_code']}")
        # Your logic here (e.g., send SMS, update CRM)

    elif event == "appointment.canceled":
        print(f"Cancellation: {payload['data']['search_code']}")
        # Your logic here

    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(`New appointment: ${data.search_code}`);
      // Your logic here
      break;
    case "appointment.canceled":
      console.log(`Cancellation: ${data.search_code}`);
      break;
  }

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

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

Best practices

1. Respond quickly — Return 200 as fast as possible. Process heavy logic in the background
2. Idempotency — Your application may receive the same event more than once. Use the appointment_key to check for duplicates
3. HTTPS required — Always use HTTPS for the webhook URL
4. Logging — Log all received notifications for debugging
5. Retry — If your application returns an error (status != 2xx), eAgenda may attempt to resend the notification
6. Validation — Validate the received content before processing