Webhook Integration

Mit Webhooks kannst du beliebige Systeme proaktiv über bevorstehende Abfuhrtermine informieren – ganz ohne Polling. müll.io sendet einen HTTP-POST an deine URL, sobald eine Abfuhr in der konfigurierten Anzahl von Tagen bevorsteht.

Webhooks lassen sich direkt über die API anlegen und löschen. Einsatzbeispiele: n8n / Make-Automationen, Discord- oder Slack-Bots, ntfy.sh-Nachrichten, Home-Automation-Systeme oder eigene Anwendungen.

---

1. API-Key anlegen

Um Webhooks anlegen zu können, brauchst du zunächst einen API-Key. Registriere deine E-Mail-Adresse und du erhältst deinen Key per E-Mail.

Kostenlos API-Key anfordern

---

2. Webhook anlegen

Sende einen POST-Request an /api/webhook mit deinem API-Key im Header. Die Adresse wird direkt im Request-Body übergeben.

curl -X POST https://müll.io/api/webhook \
  -H "Authorization: API-KEY <dein-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mein-server.example/webhook",
    "daysBeforeCollection": 1,
    "street": "Musterstraße",
    "houseNumber": "1a",
    "zip": "12345",
    "city": "Musterstadt",
    "country": "DE"
  }'

Die Antwort enthält die id und das secret des Webhooks:

{
  "id": "018f1e2a-3b4c-7d5e-8f9a-0b1c2d3e4f56",
  "url": "https://mein-server.example/webhook",
  "secret": "a3f8b1c2d4e5...",
  "daysBeforeCollection": 1,
  "active": true
}

---

3. Payload & Signaturprüfung

müll.io sendet täglich um 18:00 Uhr einen POST an alle aktiven Webhooks, wenn eine Abfuhr in der eingestellten Anzahl von Tagen bevorsteht:

{
  "event": "upcoming_collection",
  "sent_at": "2024-01-14T18:00:00+00:00",
  "days_until": 1,
  "address": {
    "street": "Musterstraße",
    "houseNumber": "1a",
    "zip": "12345",
    "city": "Musterstadt",
    "country": "DE"
  },
  "collections": [
    { "type": "Restmüll", "date": "2024-01-15" },
    { "type": "Papier",   "date": "2024-01-15" }
  ]
}

Jeder Request enthält den Header X-Muell-Signature: sha256=<hmac>. Verifizierung in Node.js:

const crypto = require('crypto');

function verifySignature(body, secret, signatureHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

---

4. Webhook löschen

curl -X DELETE https://müll.io/api/webhook/018f1e2a-3b4c-7d5e-8f9a-0b1c2d3e4f56 \
  -H "Authorization: API-KEY <dein-api-key>"

Bei Erfolg antwortet der Server mit HTTP 204 (kein Body).

---

← Übersicht der Integrationen  ·  Vollständige API-Dokumentation