Vai al contenuto

Integrazione Webhook

Con i webhook puoi informare proattivamente qualsiasi sistema sulle date di raccolta imminenti – senza alcun polling. binable invia una richiesta HTTP POST al tuo URL non appena una raccolta è prevista entro il numero di giorni configurato.

I webhook possono essere creati ed eliminati direttamente tramite l'API. Esempi d'uso: automazioni n8n / Make, bot Discord o Slack, messaggi ntfy.sh, sistemi di home automation o applicazioni personalizzate.

1. Creare una chiave API

Per poter creare webhook, hai bisogno prima di una chiave API. Registra il tuo indirizzo e-mail e riceverai la tua chiave via e-mail.

Richiedi una chiave API gratuita

2. Creare un webhook

Invia una richiesta POST a /api/webhook con la tua chiave API nell'header. L'indirizzo viene trasmesso direttamente nel body della richiesta.

curl -X POST https://binable.app/api/webhook \
  -H "Authorization: ApiKey <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"
  }'

La risposta contiene l'id e il secret del webhook:

{
  "id": "018f1e2a-3b4c-7d5e-8f9a-0b1c2d3e4f56",
  "url": "https://mein-server.example/webhook",
  "secret": "a3f8b1c2d4e5...",
  "daysBeforeCollection": 1,
  "active": true
}
Il secret viene restituito una sola volta – alla creazione. Conservalo in modo sicuro, ti serve per la verifica della firma.

3. Payload e verifica della firma

binable invia ogni giorno alle 18:00 una richiesta POST a tutti i webhook attivi, quando una raccolta è prevista entro il numero di giorni impostato:

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

Ogni richiesta contiene l'header X-Muell-Signature: sha256=<hmac>. Verifica 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. Eliminare un webhook

curl -X DELETE https://binable.app/api/webhook/018f1e2a-3b4c-7d5e-8f9a-0b1c2d3e4f56 \
  -H "Authorization: ApiKey <dein-api-key>"

In caso di successo il server risponde con HTTP 204 (nessun body).

← Panoramica delle integrazioni  ·  Documentazione API completa