Saltar al contenido

Integración de webhook

Con webhooks puede informar de forma proactiva a cualquier sistema sobre las próximas fechas de recogida, sin necesidad de sondeo. binable envía un HTTP POST a su URL en cuanto una recogida está prevista dentro del número de días configurado.

Los webhooks pueden crearse y eliminarse directamente a través de la API. Casos de uso: automatizaciones con n8n / Make, bots de Discord o Slack, mensajes de ntfy.sh, sistemas de automatización del hogar o aplicaciones propias.

1. Crear clave de API

Para crear webhooks, primero necesita una clave de API. Registre su dirección de correo electrónico y recibirá su clave por correo.

Obtener clave de API gratuita

2. Crear webhook

Envíe una solicitud POST a /api/webhook con su clave de API en la cabecera. La dirección se pasa directamente en el cuerpo de la solicitud.

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 respuesta contiene el id y el secret del webhook:

{
  "id": "018f1e2a-3b4c-7d5e-8f9a-0b1c2d3e4f56",
  "url": "https://mein-server.example/webhook",
  "secret": "a3f8b1c2d4e5...",
  "daysBeforeCollection": 1,
  "active": true
}
El secret solo se devuelve una vez, al crear el webhook. Guárdelo de forma segura, lo necesita para la verificación de firma.

3. Payload y verificación de firma

binable envía un POST a todos los webhooks activos diariamente a las 18:00 cuando una recogida está prevista dentro del número de días configurado:

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

Cada solicitud contiene la cabecera X-Muell-Signature: sha256=<hmac>. Verificación en 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. Eliminar webhook

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

Si tiene éxito, el servidor responde con HTTP 204 (sin cuerpo).

← Vista general de integraciones  ·  Documentación completa de la API