Webhooks

Los webhooks de Kids Solutions notifican a tu backend cuando ocurren eventos relevantes (registro de usuario, upgrade a Premium, click afiliado, etc.). Crea suscripciones desde el dashboard /developers (tab Webhooks) o vía API si tu key tiene scope webhooks:write.

Eventos disponibles

• user.created — usuario completó onboarding
• user.deleted — cuenta eliminada
• subscription.upgraded — upgrade a Family o Premium
• subscription.canceled — downgrade a free
• product.viewed — click registrado (afiliado o catálogo)
• wishlist.added — producto guardado en wishlist
• wishlist.removed — producto removido
• order.intent — intención de compra detectada
• family.invited — invitación a familia enviada

Formato del payload

POST con Content-Type: application/json:

{
  "id": "delivery_uuid",
  "event": "wishlist.added",
  "created_at": "2026-06-03T12:34:56Z",
  "data": {
    "product_id": "uuid",
    "child_id": "uuid_or_null",
    "target_price": 29.90
  }
}

Headers HTTP

• X-Kids-Signature — HMAC SHA256 hex del body, con tu signing secret
• X-Kids-Event — nombre del evento
• X-Kids-Delivery — id único de esta delivery (para idempotencia)
• User-Agent: KidsSolutions-Webhooks/1.0

Verificación de firma (Node.js)

import crypto from 'node:crypto'

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  )
}

app.post('/webhook', (req, res) => {
  const sig = req.headers['x-kids-signature']
  if (!verify(req.rawBody, sig, process.env.WHSEC)) {
    return res.status(401).send('invalid signature')
  }
  // procesar evento...
  res.status(200).send('ok')
})

Retry policy

• Cualquier código fuera del rango 2xx se considera fallo.
• Reintentos automáticos con backoff exponencial: 2 min, 4 min, 8 min, 16 min, 32 min.
• Máximo 5 intentos. Tras el último fallo, la delivery queda en estado failed.
• El cron de despacho corre cada 5 minutos.
• Tu endpoint debe responder en menos de 8 segundos (timeout del cron).

Best practices

• Responde 200 OK lo antes posible y procesa el evento de forma asíncrona.
• Implementa idempotencia usando X-Kids-Delivery como deduplication key.
• Loguea el body completo durante desarrollo para depurar.
• Rota el signing secret periódicamente (recrea el webhook).
• En producción usa HTTPS — los webhooks no se entregan a HTTP plano salvo desarrollo.

Test ping

Desde el dashboard puedes lanzar un evento test.ping al target URL para verificar que la firma y el formato son correctos.