Naar inhoud springen

Webhook Integratie

Met webhooks kunt u elk systeem proactief informeren over aankomende inzameldatums – zonder polling. müll.io stuurt een HTTP POST naar uw URL zodra een inzameling is gepland in het geconfigureerde aantal dagen.

Webhooks kunnen rechtstreeks via de API worden aangemaakt en verwijderd. Gebruiksscenario's: n8n / Make automatiseringen, Discord- of Slack-bots, ntfy.sh-berichten, domoticasystemen of aangepaste applicaties.

1. API-sleutel aanmaken

Om webhooks aan te maken, heeft u eerst een API-sleutel nodig. Registreer uw e-mailadres en u ontvangt uw sleutel per e-mail.

Gratis API-sleutel aanvragen

2. Webhook aanmaken

Stuur een POST-verzoek naar /api/webhook met uw API-sleutel in de header. Het adres wordt rechtstreeks in de verzoekbody doorgegeven.

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"
  }'

Het antwoord bevat het id en geheim van de webhook:

{
  "id": "018f1e2a-3b4c-7d5e-8f9a-0b1c2d3e4f56",
  "url": "https://mein-server.example/webhook",
  "secret": "a3f8b1c2d4e5...",
  "daysBeforeCollection": 1,
  "active": true
}
Het geheim wordt slechts eenmaal geretourneerd – bij het aanmaken van de webhook. Sla het veilig op, u heeft het nodig voor handtekeningverificatie.

3. Payload & handtekeningverificatie

müll.io stuurt dagelijks om 18:00 uur een POST naar alle actieve webhooks wanneer een inzameling gepland is in het geconfigureerde aantal dagen:

{
  "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" }
  ]
}

Elk verzoek bevat de header X-Muell-Signature: sha256=<hmac>. Verificatie 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 verwijderen

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

Bij succes antwoordt de server met HTTP 204 (geen body).

← Overzicht integraties  ·  Volledige API-documentatie