Saltar al contenido principal

Webhooks

Los webhooks son una parte esencial del proceso de integración. Permiten que tu aplicación reciba notificaciones automáticas cuando se ejecutan acciones dentro de Amplify.

De esta forma, tu sistema puede reaccionar en tiempo real ante eventos como la creación de una intención de pago o la confirmación de un pago.

Configuración

Para configurar tus webhooks necesitás tener una cuenta en Amplify.

Una vez dentro de tu perfil, podés definir la URL donde querés recibir las notificaciones desde el panel de administración:

https://getamplify.app/plataforma/webhooks

Allí deberás indicar la URL pública de tu backend que recibirá los eventos.

Integración

Amplify enviará la información mediante un HTTP POST a la URL que hayas configurado.

Tu servidor debe:

  1. Exponer un endpoint accesible públicamente.
  2. Aceptar requests POST.
  3. Procesar el body enviado por Amplify.

Ejemplo básico con Node.js y Express​

Definición de ruta​

// routes.js
app.post("/api/amplify/webhook", (req, res) => {
  AmplifyController.webhook(req, res);
});

Controlador​

// AmplifyController.js
function webhook(req, res) {
  const { body } = req;
  const { topic, transaction } = body;

  console.log("TOPIC", topic);
  console.log("TRANSACTION", transaction);

  res.status(200).send("ok");
}

Es importante responder con un HTTP 200 para confirmar la correcta recepción del webhook.

Tipos de Webhooks

Actualmente existen dos tipos de eventos:

  • PAYMENT_INTENT_CREATED
  • PAYMENT_CREATED

PAYMENT_INTENT_CREATED​

Se ejecuta cuando un usuario crea una intención de pago.
Esto significa que el SDK se renderizó correctamente dentro de tu integración.

Ejemplo​

{
  "topic": "PAYMENT_INTENT_CREATED",
  "transaction": {
    "paymentIntentId": "123...abc",
    "receiverId": "123...abc",
    "status": "CREATED",
    "metadata": {
      "randomKey": "randomValue"
    }
  }
}

Campos relevantes​

  • paymentIntentId: Identificador de la intención de pago.
  • receiverId: Identificador del cliente.
  • status: Estado actual de la intención.
  • metadata: Información adicional enviada al crear la intención.

PAYMENT_CREATED​

Se ejecuta cuando un pago fue procesado correctamente.

Este webhook contiene toda la información necesaria para actualizar tu sistema (orden, suscripción, acceso, etc.).

Ejemplo​

{
  "topic": "PAYMENT_CREATED",
  "transaction": {
    "paymentId": "123...abc",
    "receiverId": "123...abc",
    "amount": "1.0",
    "token": "USDC",
    "chain": "mumbai",
    "metadata": {
      "randomKey": "randomValue"
    },
    "symbol": "USDC"
  }
}

Campos relevantes​

  • paymentId: Identificador único del pago.
  • receiverId: Identificador del cliente.
  • amount: Monto pagado.
  • token: Token utilizado.
  • chain: Red blockchain utilizada.
  • symbol: Símbolo del token.
  • metadata: Información adicional enviada en la intención de pago.

Buenas prácticas

  • Validar que el topic sea uno esperado antes de procesar la información.
  • Confirmar que el receiverId corresponda a un cliente válido en tu sistema.
  • Evitar lógica pesada directamente en el endpoint (usar colas o procesamiento asíncrono si es necesario).
  • Registrar logs para auditoría y debugging.