DecisaDocumentación

Documentación · Integraciones

Conecta una plataforma de checkout.

Cada integración incluye su propio receptor de webhooks y su mapeador canónico. La verificación de la firma HMAC es obligatoria en toda ruta de webhook — sin excepciones.

Verificación HMAC, siempre

Toda solicitud de webhook debe pasar la verificación de la firma HMAC antes de que Decisa escriba algo en la base de datos. No aceptamos el atajo de "simplemente deshabilítalo durante la configuración": un secreto de webhook incorrecto devolverá 401 cada vez, y el mensaje de diagnóstico te indica qué encabezado revisar.

El secreto compartido vive en la configuración de tu workspace en Integrations → [provider] → Webhook secret. Rótalo cuando quieras; el receptor acepta el secreto anterior durante 5 minutos tras la rotación para que las solicitudes en curso sobrevivan al cambio.

Seguridad ante reenvíos

Todos los proveedores reintentan. Asumimos que la entrega duplicada es lo normal. La idempotencia se aplica en dos capas:

  • Unicidad de raw_payload en (workspace_id, provider, event_id): el mismo webhook no puede crear dos filas raw.
  • Unicidad de la conversión canónica en (workspace_id, external_id): mapear distintos payloads raw al mismo evento de negocio nunca crea duplicados aguas abajo.

Proveedores compatibles

Shopify

Disponible de forma general

POST /api/webhooks/shopify

  • orders/create
  • orders/paid
  • orders/refunded

Configura el webhook en Shopify Admin → Settings → Notifications. Decisa deriva el external_id del order id y el visitor_id del atributo de nota del pedido dcs_vid (poblado automáticamente por el pixel en el checkout).

Stripe

Disponible de forma general

POST /api/webhooks/stripe

  • checkout.session.completed
  • invoice.paid
  • customer.subscription.created

Configura un endpoint de webhook en Stripe Dashboard → Developers → Webhooks. El emparejamiento de visitantes usa el campo metadata.dcs_vid: establécelo desde el cliente al crear el checkout.

Kiwify

Beta

POST /api/webhooks/kiwify

  • order.approved
  • subscription.renewed
  • order.refunded

Agrega la URL del webhook en Kiwify → Settings → Webhooks. El visitor_id se extrae del parámetro de consulta ?_v=… de la URL de la oferta que el pixel agrega a los enlaces de checkout salientes.

Custom backend

Siempre disponible

POST /v1/conversions

  • Any conversion type

Cuando ningún webhook canónico cubre tu plataforma, llama a /v1/conversions directamente desde tu backend. Consulta la referencia de la API para conocer el contrato completo del payload.

Lo que deliberadamente no hemos abstraído

No existe una interfaz universal de "adaptador de checkout" en el código. Cada proveedor vive en su propio espacio de nombres (App\Integrations\Checkout\Shopify, etc.) con su propio mapeador, su propio esquema de payload raw y su propia lógica de verificación HMAC. No extraeremos un adaptador compartido hasta que tres proveedores independientes estén en producción y los patrones sean evidentes.

Esto es intencional. La abstracción prematura es el error más costoso en el código de integraciones — una vez que generalizas la forma equivocada, cada nuevo proveedor se convierte en un rompecabezas.

¿Necesitas un proveedor que aún no tenemos? Escríbenos a [email protected] con un payload de webhook de muestra — normalmente lo lanzamos en menos de una semana. O usa hoy mismo el endpoint genérico /v1/conversions desde tu backend.