Skip to content

Webhook Integration

With webhooks you can proactively inform any systems about upcoming pickup dates – without polling. müll.io sends an HTTP POST to your URL as soon as a pickup is due in the configured number of days.

Webhooks can be created and deleted directly via the API. Use cases: n8n / Make automations, Discord or Slack bots, ntfy.sh messages, home automation systems or custom applications.

1. Create API key

To create webhooks, you first need an API key. Register your email address and you will receive your key by email.

Get free API key

2. Create webhook

Send a POST request to /api/webhook with your API key in the header. The address is passed directly in the request body.

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

The response contains the id and secret of the webhook:

{
  "id": "018f1e2a-3b4c-7d5e-8f9a-0b1c2d3e4f56",
  "url": "https://mein-server.example/webhook",
  "secret": "a3f8b1c2d4e5...",
  "daysBeforeCollection": 1,
  "active": true
}
The secret is only returned once – when creating the webhook. Store it securely, you need it for signature verification.

3. Payload & signature verification

müll.io sends a POST to all active webhooks daily at 6:00 PM when a pickup is due in the configured number of days:

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

Each request contains the header X-Muell-Signature: sha256=<hmac>. Verification 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. Delete webhook

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

On success, the server responds with HTTP 204 (no body).

← Integration overview  ·  Full API documentation