Inscripción de Webhook Endpoints

📘

Esta sección explica el proceso de creación de Webhook Endpoints a través de la API REST de Toku. También puedes verlo en la documentación de la API aquí.

Para ciertos eventos, Toku permite la integración a través de Webhook Endpoints. Con esto, puedes registrar endpoints en donde Toku notifique la ocurrencia de eventos específicos. En este momento, los eventos que pueden registrarse son:

  • 'interaction.incoming': Interaction entrante desde un Customer hacia Toku.
  • 'interaction.outgoing': Interaction saliente desde Toku hacia un Customer.
  • 'payment_method.attached': Customer ha inscrito un método de pago en la plataforma.
  • 'payment_intent.succeeded': Intento de pago exitoso de un Invoice.
  • 'payment_intent.payment_failed': Intento de pago fallido de un Invoice.
  • 'payment_intent.payment_succeeded_batch': Resumen de pagos exitosos para una lista de Invoices. Se utiliza en procesos de cobro automático masivos
  • 'payment_intent.payment_failed_batch': Resumen de intentos de pagos fallidos para una lista de Invoices. Se utiliza en procesos de cobro automático masivos

Para registrar un **Webhook Endpoint, debes poseer un endpoint que pueda recibir datos a través de una request POST, y que confirme su recepción retornando un status code HTTP 2xx.

🚧

Solo es necesario inscribir una vez el endpoint. Después de inscrito, notificará los eventos inscritos.

A continuación, te explicamos cómo inscribir un Webhook Endpoint a través de una request POST a la API.

POST /webhook_endpoints

Parámetros para crear Webhook Endpoint

Nombre

Tipo

Descripción

Requerido

enabled_events

list

Lista de eventos a la que se suscribe este Webhook Endpoint.

:radio-button: Si

url

string

URL de tu endpoint, al cual se le notificarán los eventos mediante requests POST.

:radio-button: Si

status

string

Estado del Webhook Endpoint. Si es enabled, enviará notificaciones de los eventos suscritos. En caso contrario definir como disabled.

:white-circle: No

{
  "enabled_events": [
    "payment_method.attached",
        "payment_intent.succeeded"
  ],
  "status": "enabled",
  "url": "https://prueba.com"
}

La respuesta recibida es de la forma:

{
  "enabled_events": [
    "payment_method.attached",
        "payment_intent.succeeded"
  ],
  "status": "enabled",
  "url": "https://prueba.com",
    "id": "whe_oJJDbbiXBgwOEzpIBzJMWAids_5xgmHS",
    "secret": "whesec_DTouU4ek2-tMhBO9sBUZNVC8tIIJuZsn"
}

❗️

Importante

Luego de cada creación de Webhook Endpoints, se deben almacenar los campos id y secret, los cuales son utilizados para las verificaciones de seguridad explicadas en la siguiente sección.

Luego de inscrito, puedes hacer una request PUT /webhook_endpoints/{id} para hacer las siguientes modificaciones:

  • Editar la lista de eventos, enviando el parametro enabled_events
  • Deshabilitar el endpoint para no seguir recibiendo eventos, enviando el parametro statuscomo disabled

Siguientes pasos

Con el ejemplo anterior, Toku notificará cada vez que se inscriba un método de pago o se realice un cobro de manera exitosa. Lo hará a través de una request POST a la URL suscrita, en este caso https://prueba.com. Debes tener habilitado este endpoint para poder recibir y almacenar la información que se le envíe.