Webhook API

Conceptos Generales

Un webhook es una retrollamada HTTP, una solicitud HTTP POST que interviene cuando ocurre algún evento. Los webhooks se utilizan para las notificaciones en tiempo real, por lo que el sistema puede actualizarse cuando se produce el evento.

Puede configurar sus webhooks a través de la API para recibir notificaciones sobre eventos que sucedan en su cuenta de Zenrise.

Crear un webhook

URL : /v1/webhook

Método : POST

Requiere autorización : Sí, ver Autenticación

Parámetros

events `required`

La lista de eventos disponibles actualmente.

Valores aceptados	Descripción
subscription.create	Ocurre cuando se crea una suscripción.
subscription.cancelled	Ocurre cuando se cancela una suscripción.
subscription.update	Ocurre cuando se actualiza/hay un cambio de estado en una suscripción.
transfer.create	Ocurre cuando se solicita una transferencia.
transfer.update	Ocurre cuando se actualiza la transferencia y pasa a estado en progreso o reversa.
transfer.finish	Ocurre cuando la transferencia se finaliza.
wallet_transfer_entry.finish	Ocurre cuando se acredita una transferencia entrante.

url `required`

La url del webhook.

description ==optional==

Una descripción opcional de para qué se utiliza el webhook.

Ejemplo

Request:

{
  "description": "This is my webhook!!!",
  "externalReference": "my_external_reference",
  "events": [
    "subscription.create",
    "subscription.cancelled"
  ],
  "url": "https://myendpoint.com/webhook/subscription"
}

Response:

{
  "id": 2,
  "description": "This is my webhook!!!",
  "externalReference": "my_external_reference",
  "events": [
    "subscription.create",
    "subscription.cancelled"
  ],
  "enabled": true,
  "url": "https://myendpoint.com/webhook/subscription"
}

Consultar webhooks

URL : /v1/webhook

Método : GET

Requiere autorización : Sí, ver Autenticación

Devuelve los webhooks de su organización, paginados.

Parámetros (query)

page ==optional==

Número de página (empieza en 0). Por defecto 0.

size ==optional==

Cantidad de resultados por página. Por defecto 10.

Ejemplo

Request: GET /v1/webhook?page=0&size=10

Response:

{
  "data": [
    {
      "id": 2,
      "description": "This is my webhook!!!",
      "externalReference": "my_external_reference",
      "events": [
        "transfer.finish"
      ],
      "enabled": true,
      "url": "https://myendpoint.com/webhook/transfer"
    }
  ],
  "countPerPage": 1,
  "totalCount": 1,
  "metaData": {}
}

Para consultar un webhook puntual:

URL : /v1/webhook/{webHookId}

Método : GET

Devuelve el mismo objeto que se muestra dentro de data.

Use este endpoint para verificar a qué eventos está suscripto un webhook antes de asumir que va a recibir una notificación.

Actualizar un webhook

URL : /v1/webhook/{webHookId}

Método : PUT

Requiere autorización : Sí, ver Autenticación

Todos los campos son opcionales: sólo se modifican los campos que se envían en el body. Los que no se envían conservan su valor actual.

Parámetros

events ==optional==

La lista completa de eventos a los que el webhook debe quedar suscripto (ver valores aceptados en Crear un webhook).

Importante: este campo reemplaza la lista de eventos actual, no agrega. Si quiere sumar un evento a un webhook existente, debe enviar los eventos que ya tenía más el nuevo. Por ejemplo, un webhook suscripto a transfer.finish que quiera recibir además las reversas debe enviar ["transfer.finish", "transfer.update"]; si envía sólo ["transfer.update"] deja de recibir transfer.finish.

url ==optional==

La nueva url del webhook.

description ==optional==

Descripción del webhook.

externalReference ==optional==

Referencia externa del webhook.

enabled ==optional==

true / false. Un webhook deshabilitado no recibe notificaciones de ningún evento.

Ejemplo

Request: PUT /v1/webhook/2

{
  "events": [
    "transfer.finish",
    "transfer.update"
  ]
}

Response:

{
  "id": 2,
  "description": "This is my webhook!!!",
  "externalReference": "my_external_reference",
  "events": [
    "transfer.finish",
    "transfer.update"
  ],
  "enabled": true,
  "url": "https://myendpoint.com/webhook/transfer"
}

Eliminar un webhook

URL : /v1/webhook/{webHookId}

Método : DELETE

Requiere autorización : Sí, ver Autenticación

Elimina el webhook. A partir de ese momento no se envían más notificaciones a esa url. Responde 200 OK sin body.

Webhook Notification

Cuando ocurre un evento, enviamos una notificación a todos los webhooks asociados a ese evento. El modelo de datos enviados es el siguiente.

Aclaración: Los webhooks siguen funcionando para suscripciones gratuitas.

{
  "event": "subscription.create",
  "object": {
    "id": 1,
    "status": "TRIALING",
    "description": null,
    "planId": 123,
    "subscriptionConfiguration": {
      "id": 9925,
      "startDate": "2021-02-01",
      "periods": 3,
      "amountAfterFirstDueDate": null,
      "amountAfterSecondDueDate": null,
      "firstDuePercentage": 0.0,
      "secondDuePercentage": 0.0,
      "endDate": "2021-05-30",
      "lastFourDigits": "4792",
      "collectType": "CHARGE",
      "chargeType": "CARD",
      "daysAfterFirstDue": 10,
      "daysAfterSecondDue": 15
    },
    "contact": {
      "id": 1,
      "externalReference": "id-externo-123"
    },
    "metadata": {
      "someData": "data"
    },
    "billingDates": {
      "startBillingDate": "2021-01-31",
      "nextBillingDate": "2021-02-01"
    }
  }
}

event es el evento en cuestión (revisar la lista de eventos disponibles).
object es el objeto asociado al evento

Notificación de suscripción

billingDates es el objeto que representa el período que está vigente en la suscripción.

startBillingDate: Representa el inicio del período
nextBillingDate: Representa la siguiente fecha en la que se va a cobrar

Ejemplos

Suscripción inicio a futuro Si creamos una suscripción a futuro, esta suscripción nace con un estado TRIALING donde startBillingDate es la fecha en la que se crea y nextBillingDate es la fecha de inicio de la suscripción.

Suscripción inicio al día de creación Si creamos una suscripción para ese mismo día, esta suscripción nace con un estado ACTIVE donde startBillingDate y nextBillingDate es la misma fecha, es decir la fecha de ese día.

Suscripción inicio fecha anterior al día de hoy Si creamos una suscripción con fecha de inicio anterior al día en que se crea, la suscripción nace con un estado ACTIVE donde startBillingDate es la fecha de inicio de la suscripción y nextBillingDate es la fecha de creación.

Suscripción que se cancela Si la suscripción está en estado ACTIVE, hoy es 2021-02-15, el último cobro de la suscripción fue en la fecha 2021-02-01 y la suscripción se cancela, nos llegará un webhook con el estado CANCELED donde el startBillingDate es 2021-02-01 y el nextBillingDate 2021-03-01, donde en este caso nextBillingDate también representa la fecha de finalización de la suscripción.

Webhook para eventos de Suscripción

Para los casos de subscription.update y subscription.cancelled revisar los ciclos de vida de la Suscripción.

Cuando hay un cambio de estado que no sea cancelled, lo notificamos a través de subscription.update

Webhook para eventos de Transferencia

Los eventos de transferencia permiten recibir notificaciones en tiempo real sobre el ciclo de vida de una transferencia saliente. Para recibir estas notificaciones, el webhook debe estar suscripto a los eventos correspondientes (transfer.create, transfer.update, transfer.finish).

Importante: Las notificaciones de reversa se envían a través del evento transfer.update. No existe un evento específico de reversa. Si tu webhook ya incluye transfer.update en la lista de eventos, recibirás automáticamente las notificaciones de reversa.

Si tu webhook está suscripto solamente a transfer.finish, no vas a recibir las reversas: para una transferencia que se acredita y luego se reversa vas a recibir únicamente el transfer.finish con status: "Accredited". En ese caso tenés que sumar transfer.update a la lista de eventos con Actualizar un webhook (enviando la lista completa, por ejemplo ["transfer.finish", "transfer.update"]).

Tené en cuenta que transfer.update también se envía cuando la transferencia pasa a InProgress, por lo que para detectar una reversa hay que mirar el campo object.status ("Reversed") y no sólo el nombre del evento.

Ejemplos de webhook de transferencia

transfer.create

{
  "event": "transfer.create",
  "object": {
    "status": "Pending",
    "amount": 100,
    "externalReference": null,
    "requestDate": "2022-09-20T12:31:29.839",
    "bankAccountId": "3721",
    "coelsaId": null,
    "id": 10766,
    "cbvuNumber": "0000128000000000000000"
  }
}

transfer.update

Este webhook se dispara cuando la transferencia pasa a estado InProgress o Reversed.

{
  "event": "transfer.update",
  "object": {
    "status": "InProgress",
    "amount": 100,
    "externalReference": null,
    "requestDate": "2022-09-20T12:31:29.839",
    "bankAccountId": "3721",
    "coelsaId": "hJJkklmNop56Y",
    "id": 10766,
    "cbvuNumber": "0000128000000000000000"
  }
}

{
  "event": "transfer.update",
  "object": {
    "id": 123,
    "status": "Reversed",
    "bankAccountId": "1111111",
    "requestDate": "2026-05-05T13:39:56",
    "externalReference": "my-external-reference",
    "coelsaId": "hJJkklmNop56Y",
    "amount": 20000.0,
    "cbvuNumber": "0200356411000000000000"
  }
}

transfer.finish
Este webhook puede dispararse cuando la transferencia pasa a Accredited o Fail

{
  "event": "transfer.finish",
  "object": {
    "status": "Accredited",
    "amount": 100,
    "externalReference": null,
    "requestDate": "2022-09-20T12:31:29.839",
    "bankAccountId": "3721",
    "coelsaId": "hJJkklmNop56Y",
    "id": 10766,
    "cbvuNumber": "0000128000000000000000"
  }
}

{
  "event": "transfer.finish",
  "object": {
    "status": "Fail",
    "amount": 100,
    "externalReference": null,
    "requestDate": "2022-09-20T12:31:29.839",
    "bankAccountId": "3721",
    "coelsaId": "hMMkklmNop77Y",
    "id": 10766,
    "cbvuNumber": "0000128000000000000000"
  }
}

Webhook para eventos de Transferencias Entrantes

Una wallet_transfer_entry representa una transferencia entrante a la cuenta. El único evento disponible es wallet_transfer_entry.finish, que se emite cuando la transferencia se acredita sin pasar por estados intermedios.

wallet_transfer_entry.finish

{
  "event": "wallet_transfer_entry.finish",
  "object": {
    "id": 20045501,
    "status": "Accredited",
    "amount": 1000,
    "holderName": "Juan Pérez",
    "holderCuit": "20123456789"
  }
}

Campos

status: Accredited indica que la transferencia se acreditó.

holderName: nombre del titular que envió la transferencia.

holderCuit: CUIT del titular.

amount: monto acreditado.

Conceptos Generales​

Crear un webhook​

Parámetros​

events required​

url required​

description ==optional==​

Ejemplo​

Consultar webhooks​

Parámetros (query)​

page ==optional==​

size ==optional==​

Ejemplo​

Actualizar un webhook​

Parámetros​

events ==optional==​

url ==optional==​

description ==optional==​

externalReference ==optional==​

enabled ==optional==​

Ejemplo​

Eliminar un webhook​

Webhook Notification

Notificación de suscripción​

Webhook para eventos de Suscripción

Webhook para eventos de Transferencia

Webhook para eventos de Transferencias Entrantes

Conceptos Generales

Crear un webhook

Parámetros

events `required`

url `required`

description ==optional==

Ejemplo

Consultar webhooks

Parámetros (query)

page ==optional==

size ==optional==

Ejemplo

Actualizar un webhook

Parámetros

events ==optional==

url ==optional==

description ==optional==

externalReference ==optional==

enabled ==optional==

Ejemplo

Eliminar un webhook

Notificación de suscripción