Saltar para o conteúdo

Integração de Webhook

Com webhooks pode informar proativamente quaisquer sistemas sobre as próximas datas de recolha – sem polling. O binable envia um HTTP POST para o seu URL assim que uma recolha estiver prevista dentro do número de dias configurado.

Os webhooks podem ser criados e eliminados diretamente através da API. Casos de utilização: automatizações n8n / Make, bots do Discord ou Slack, mensagens ntfy.sh, sistemas de domótica ou aplicações próprias.

1. Criar chave de API

Para criar webhooks, precisa primeiro de uma chave de API. Registe o seu endereço de e-mail e receberá a chave por e-mail.

Obter chave de API gratuita

2. Criar webhook

Envie um pedido POST para /api/webhook com a sua chave de API no cabeçalho. A morada é transmitida diretamente no corpo do pedido.

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

A resposta contém o id e o secret do webhook:

{
  "id": "018f1e2a-3b4c-7d5e-8f9a-0b1c2d3e4f56",
  "url": "https://mein-server.example/webhook",
  "secret": "a3f8b1c2d4e5...",
  "daysBeforeCollection": 1,
  "active": true
}
O secret só é devolvido uma vez – ao criar o webhook. Guarde-o em segurança, pois é necessário para a verificação da assinatura.

3. Payload e verificação da assinatura

O binable envia diariamente, às 18:00, um POST a todos os webhooks ativos quando uma recolha está prevista dentro do número de dias 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 pedido contém o cabeçalho X-Binable-Signature: sha256=<hmac>. Verificação em 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>"

Em caso de sucesso, o servidor responde com HTTP 204 (sem corpo).

n8n
Automatizar as datas de recolha em fluxos de trabalho
API
Datas de recolha através de API HTTP para as suas próprias aplicações
Home Assistant
Datas de recolha como sensores e calendário

← Vista geral das integrações  ·  Documentação completa da API