Webhook

Los Webhooks son una manera simple de comunicar diferentes servicios. Un webhook es un endpoint donde puedes ejecutar una acción o serie de acciones cuando una petición llega.

Los Webhooks son un excelente complemento a las APIs que ofrece Ingenio Market.

Basicamente el funcionamiento implica que al realizarse un evento (por ejemplo registro de un usuario) se envia un Json POST a la url (endpoint) del webhook. Luego tu podrás realizar la tarea que consideres o incluso consultar nuestra

Configuración

Para crear un webhook debes ir a la sección de integraciones y desde ahi crearlo. Deberás ingresar el endpoint(URL) y los eventos de los cuales queres recibir notificaciones.

Notificaciones

Cada solicitud enviada por el webhook contendrá en el cuerpo de la misma una versión codificada en JSON de los datos relacionados al evento. La solicitud tendrá un encabezado llamado Signatureque que contendrá una firma que la aplicación receptora puede usar para verificar que la carga útil no haya sido manipulada.

Eventos Disponibles

Seguridad: verificación de la firma

Cada request que enviamos incluye el header Signature con una firma HMAC-SHA256 calculada sobre el body JSON. Verificar esta firma es obligatorio — sin esta validación cualquier tercero podría enviar requests falsos a tu endpoint.

La firma se calcula así:

Signature = HMAC-SHA256(body_json_crudo, tu_secret)

El secret es el valor que configuraste al crear el webhook en el panel.

Importante: la firma se calcula sobre el body antes de parsearlo. Si tu framework parsea el body automáticamente (Express, Laravel, etc.), asegurate de leer el raw body primero — de lo contrario la verificación siempre va a fallar.

Comportamiento de reintentos

Si tu endpoint no responde con un código 2xx dentro de los 3 segundos, el request se considera fallido y se reintenta automáticamente.

• Intentos: 3 en total
• Espera entre intentos: backoff exponencial (~10 segundos al segundo intento, ~100 segundos al tercero)
• Códigos aceptados: cualquier 2xx (200, 201, 204, etc.)
• Códigos que generan reintento: 4xx, 5xx y timeouts

Si tu endpoint necesita hacer procesamiento pesado (llamadas a APIs externas, consultas lentas, etc.), respondé 200 de inmediato y procesá la lógica de forma asíncrona.

Estructura del payload

Todos los eventos tienen la misma estructura base:

{
  "event": "nombre.del.evento",
  "data": {
    // objeto con los datos del evento
  }
}

Ejemplo para el evento purchase.charge:

{
  "event": "purchase.charge",
  "data": {
    "id": 1042,
    "total": 15800.00,
    "currency": "ARS",
    "status": "pagado",
    "buyer": {
      "id": 87,
      "name": "Juan Pérez",
      "email": "juan@ejemplo.com"
    },
    "created_at": "2026-06-03T14:22:00Z"
  }
}

Ejemplo completo en PHP

<?php

$secret = 'TU_SECRET_AQUI';

// Leer el body crudo ANTES de cualquier parseo
$rawBody = file_get_contents('php://input');

// Verificar la firma
$receivedSignature = $_SERVER['HTTP_SIGNATURE'] ?? '';
$expectedSignature = hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(401);
    exit(json_encode(['error' => 'Firma inválida']));
}

// Decodificar el payload
$payload = json_decode($rawBody, true);
$event   = $payload['event'] ?? null;
$data    = $payload['data']  ?? [];

// Procesar según el evento
switch ($event) {
    case 'purchase.charge':
        $orderId = $data['id'];
        // tu lógica acá
        break;

    case 'product.create':
        // tu lógica acá
        break;
}

// Responder 200 dentro de los 3 segundos
http_response_code(200);
echo json_encode(['status' => 'ok']);

Ejemplo completo en JavaScript (Node.js + Express)

const express = require('express');
const crypto  = require('crypto');

const app    = express();
const SECRET = 'TU_SECRET_AQUI';

// Usar raw body para que la firma coincida
app.use('/webhook', express.raw({ type: 'application/json' }));

function signatureIsValid(rawBody, receivedSignature) {
    const expected = crypto
        .createHmac('sha256', SECRET)
        .update(rawBody)
        .digest('hex');

    try {
        return crypto.timingSafeEqual(
            Buffer.from(expected),
            Buffer.from(receivedSignature)
        );
    } catch {
        return false;
    }
}

app.post('/webhook', (req, res) => {
    const receivedSignature = req.headers['signature'] ?? '';

    if (!signatureIsValid(req.body, receivedSignature)) {
        return res.status(401).json({ error: 'Firma inválida' });
    }

    const { event, data } = JSON.parse(req.body.toString());

    // Responder 200 antes de procesar lógica pesada
    res.status(200).json({ status: 'ok' });

    // Tu lógica acá (después de responder)
    switch (event) {
        case 'purchase.charge':
            break;
        case 'product.create':
            break;
    }
});

app.listen(3000);