Por qué testear webhooks con payloads reales
Desarrollar integraciones con webhooks sin payloads de prueba confiables lleva a bugs en producción. El error más común: asumir que todos los eventos tienen el mismo shape. GitHub puede enviar push events sin commits (forzado), Stripe incluye metadata variable según el plan del cliente, y Slack cambia structure según el tipo de mensaje.
Usar payloads generados evita tres problemas críticos: romper deploys cuando el proveedor actualiza su API, no manejar casos edge (refunds parciales, llamadas sin respuesta), y testear solo con happy path. Los payloads acá incluyen errores 550, disputas, y eventos cancelled que muchos devs olvidan.
Un ejemplo real: una startup perdió $12k porque su webhook de Stripe no manejaba payment_intent.payment_failed con error card_declined. Asumían que todos los pagos fallaban silenciosamente. Los payloads de testing revelan estos escenarios antes de deployar.
Estructura típica de payloads según proveedor
GitHub estructura eventos con action (opened, closed), repository, y el objeto afectado (issue, PR, release). Siempre incluye sender. Stripe usa type (punto notación) y anida data en object. Su patrón: resource.event (customer.created, invoice.paid).
Slack y Discord usan type numérico o string. Slack incluye event nested para app mentions, Discord diferencia interactions (type 2 = slash command, type 3 = button). Shopify usa topic con slash notation: orders/create, products/update.
Twilio es REST-style: todos los campos top-level (MessageSid, CallStatus, From). Mailgun usa event simple (delivered, bounced) con metadata en message. Conocer estos patterns acelera debugging: si ves type string + data.object, es Stripe; si ves MessageSid, es Twilio.
Casos edge que rompen integraciones
Los payloads de prueba deben incluir: arrays vacíos (GitHub push sin commits), null values (Stripe customer sin email), missing fields (Slack messages sin text cuando es file_share). También: eventos duplicados (Shopify reenvía si no recibe 200 en 5s), y payloads gigantes (Zoom recordings de 3 horas).
Errores comunes: no validar refunded: true en Stripe charges (el amount puede ser parcial), asumir que Discord interactions siempre tienen member (DMs no lo incluyen), y no chequear attempt_count en invoices (Stripe reintenta hasta 4 veces).
Un payload de Twilio con NumMedia > 0 requiere parsear MediaUrl0, MediaUrl1... dinámicamente. GitHub pull_request puede tener mergeable: null (calculando), no solo true/false. Mailgun bounces permanent vs temporary cambian la lógica de retry.
Estrategia de testing local efectiva
Usá herramientas como ngrok o webhook.site para recibir requests localmente. Configurá una ruta /webhooks/:provider que loguee el payload completo. Importante: verificá signatures (GitHub usa HMAC-SHA256, Stripe tiene su propia lib).
Estructura recomendada: un handler por provider con schema validation (Zod, Joi). Logueá payloads unknown en Sentry para detectar cambios de API. Implementá idempotency: guardá event.id o MessageSid en Redis/DB para ignorar duplicados.
Para CI/CD: commitéa payloads de ejemplo en tests/fixtures/webhooks/ y escribí tests que los pasen por tu handler. Mockeá las signatures con el secret de test. Esto previene regressions cuando refactorizás el código del webhook. La mayoría de bugs de webhooks son validations que fallan silenciosamente.