Webhook API

Conceptos Generales

Un webhook es una retrollamada HTTP, una solicitud HTTP POST que interviene cuando ocurre algun 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 : Si, ver Autenticación

Parametros

events required

La lista de eventos disponibles actualmente.

Valores aceptadosDescripción
subscription.createOcurre cuando se crea una suscripción.
subscription.cancelledOcurre cuando se cancela una suscripción.
subscription.updateOcurre cuando se actualiza/hay un cambio de estado en una suscripción.
transfer.createOcurre cuando se solicita una transferencia.
transfer.updateOcurre cuando se actualiza la transferencia y pasa a estado en progreso.
transfer.finishOcurre cuando la transferencia se finaliza.
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"
}

Para mas informacion sobre como crear, actualizar y eliminar web hooks visite nuestra documentación en stoplight.

Web Hook 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: WebHooks siguen funcionando para suscripciones gratuitas.

{
"event": "subscription.created",
"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

Notificacion suscripcion

billingDates es el objeto que representa el periodo que esta vigente en la suscripción,

startBillingDate: Representa el inicio del perido
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 subscipcion 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 dia de creación Si creamos una suscripción para ese mismo dia, esta subscipcion nace con un estado ACTIVE donde startBillingDate y nextBillingDate es la misma fecha, es decir la fecha de ese dia.

Suscripción inicio fecha anterior al día de hoy Si creamos una suscripción con fecha de inicio anterior al dia 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 creacion.

Suscripción que se cancela Si la suscripción esta en estado ACTIVE, hoy es 2021-02-15 el ultimo cobro de la suscripción fue en la fecha 2021-02-01 y la suscripción se cancela, nos llegara un webhook con el estado CANCELED donde el startBillingDate es 2021-02-01 y el nextBillingDate 2021-03-01, donde en este caso nextBillingDate tambien representa la fecha de finalizacion de la subscipcion.

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

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

{
"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"
}
}

transfer.finish
Este web hook 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"
}
}