Saltar al contenido principal

Webhooks (Deprecated)

Importante

Los webhooks son especialmente útiles para que puedas implementar de forma correcta nuestra API, ya que el tiempo que tardamos en extraer los datos varía por plataforma y oscila entre 10 y 40 segundos.

Al implementarlos correctamente, podrás activar automáticamente procesos en tu backend que dependen de los datos de ingresos de los trabajadores.

Por ejemplo, al recibir el evento employment.updated significa que los datos de empleo están disponibles y puedes detonar en tu backend una solicitud GET al endpoint /accounts/:account_id/employment

Introducción

Un webhook es la forma en la que se comunica Palenca con tu aplicación. Se logra a través de una URL que nos proporciones a la cual enviamos notificaciones/eventos para mantenerte actualizado sobre las conexiones de tus usuarios. Estos eventos se envían en formato JSON, lo que te permite activar automáticamente procesos en tu backend.

Cada vez que se genera un evento, puedes verlos en la Consola dentro de la sección Webhooks.

img.png

Implementación

Para registrar un webhook en Palenca debes seguir estos pasos:

  1. Ve a la sección de "Desarrolladores" dentro de la Consola.

  2. Abre la pestaña de "Webhooks".

  3. Da click en "Crear Webhook", esto abrira un modal con el formulario para dar de alta un nuevo webhook.

  4. Registra la URL del webhook (puedes usar una herramienta como webhook.site para probar). Debes asociar el webhook a un widget específico o bien a todas las conexiones generadas vía API (IMSS & ISSSTE).

  5. Selecciona los eventos de los que deseas recibir notificaciones.

  6. Da click en "Crear Webhook".

  7. Comparte el link del widget para probar algunas conexiones o realiza conexiones de IMSS & ISSSTE a través de nuestra API y valida que los eventos sean recibidos en la URL que registraste.

img.png

Esquema de datos de un evento

El esquema genérico de datos de un evento que notificamos vía webhook es el siguiente:

{
"data":{
"user_id": string,
"account_id": string,
"country": string,
"platform": string,
"webhook_action": string
},
"webhook_url": string
}

Algunos eventos incluirán información adicional que detallaremos más adelante en la sección Campos nuevos.

Ejemplo de evento

Los datos que recibirás de Palenca incluirán información sobre el usuario o la cuenta y la acción de webhook desencadenada.

A continuación, se muestra un ejemplo del evento que enviamos a tu URL:

{
"data": {
"user_id": "f2a6d844-22ee-455d-9d2c-deb413d78b74",
"account_id": "d86efb5b-4bbf-4f28-8576-9612430bc5e2",
"country": "mx",
"platform": "uber",
"webhook_action": "earnings.updated"
},
"webhook_url": "https://my_site.com/palenca_webhook"
}

Lista de eventos

En la siguiente tabla puedes consultar todos los eventos que enviamos. Te recomendamos visitar nuestra sección Entidades para más información.

EventoCategoríaDescripción
user.createdUsuarioSe ha creado exitosamente un usuario.
user.deletedUsuarioSe ha borrando exitosamente un usuario.
profile.updatedPerfilSe ha creado o actualizado la información del perfil de la cuenta y puedes consultarla a través de nuestra API.
earnings.updatedGananciasSe ha creado o actualizado la información de ganancias de la cuenta y puedes consultarla a través de nuestra API.
events.updatedEventosSe ha creado o actualizado la información de eventos de la cuenta y puedes consultarla a través de nuestra API.
employment.updatedEmpleoSe ha creado o actualizado la información de empleo de la cuenta y puedes consultarla a través de nuestra API.
login.createdInicio de sesiónEl usuario ha iniciado el proceso de autenticación en una cuenta.
login.successInicio de sesiónEl usuario se ha conectado exitosamente a su cuenta y se ha iniciado el proceso de extracción de datos. Ten en cuenta que una vez que el inicio de sesión es exitoso, el usuario debe esperar 12 horas para iniciar sesión nuevamente.
login.errorInicio de sesiónEl usuario no pudo conectarse exitosamente a su cuenta. Por favor, comunícate con nuestro equipo de soporte.
login.incompleteInicio de sesiónEl usuario no completó el proceso de autenticación. Este evento SOLO se enviará si han pasado más de 500 segundos y el usuario no completó con éxito el flujo de inicio de sesión.

Campos nuevos

Actualmente existen dos eventos, employment.updated y earnings.updated, que a partir de marzo de 2024 regresarán información adicional extendiendo el esquema base.

A partir de marzo de 2024 el evento de employment.updated tendrá dos nuevos campos dentro de data:

1. employment_history_status: Se refiere al estatus del proceso de extracción del historial de empleo de un trabajador afiliado al IMSS o ISSSTE por parte de Palenca. Este campo puede tomar los siguientes valores:

ClaveDefinición
completeSe pudo extraer todo el historial de empleo de un trabajador. Este valor solo se envía para casos del IMSS.
nullAún no hay información suficiente para determinar el estatus del proceso. En caso del ISSSTE, si el evento es employment.updated, si se pudo extraer información.

2. time_elapsed: El número de segundos transcurridos aproximados entre que se creó el login y se recuperaron los datos de empleo. Este campo podría tener un valor de null si el proceso de extracción de empleo no se terminó. Es importante enfatizar que esto es solo una aproximación. Es difícil dar la cifra exacta dada la asincronicidad de los procesos de extracción de datos.

A continuación, se muestra un ejemplo del evento que enviamos con los datos adicionales:

{
"data": {
"user_id": "125bfab8-e127-3b6f-be24-f3301958d44e",
"account_id": "20948fdc-6645-3b6f-bb78-a41a609f7cee",
"external_id": "4707511",
"country": "mx",
"platform": "imss",
"status_details": null,
"curp": "MENR731930HDFJNJ01",
"employment_history_status": "complete",
"time_elapsed": 16
},
"webhook_url": "https://my_site.com/palenca_webhook"
}

De igual manera, el evento de earnings.updated tendrá un nuevo campo dentro de data:

1. recovered_earning_days: Se refiere al número de días donde se recuperaron ingresos distintos de cero para un trabajador. Este campo es numérico.

A continuación, se muestra un ejemplo del evento que enviamos incluyendo el dato adicional:

{
"data": {
"webhook_action": "earnings.updated",
"user_id": "e8da8d42-fd22-4100-8eab-d48d0f7eebd4",
"account_id": "5a11027d-4ed7-4255-ba1d-81c0063896f3",
"external_id": null,
"country": "mx",
"platform": "indriver",
"status_details": null,
"phone": "5555555555",
"recovered_earning_days": 30
},
"webhook_url": "https://my_site.com/palenca_webhook"
}
Importante

Es importante notar que estos campos solo contendrán información relevante para cuentas creadas a partir de marzo de 2024.

Reintentos

Si no recibimos un código 200 o 201 dentro de los 30 segundos posteriores a la primera solicitud POST a la URL del webhook, Haremos hasta tres llamadas adicionales (deteniéndolas si recibimos un código 200 o 201), esperando ~30 segundos entre cada llamada.

Importante

Si después de 3 intentos no recibimos un código 200 o 201, dejaremos de enviar el evento a tu URL y el webhook estar inhabilitado. Puede solicitar a nuestro equipo de soporte que lo vuelva a habilitar después de solucionar el problema subyacente. No almacenamos en búfer los webhooks mientras están deshabilitados.

Ejemplos de eventos:

user.created

{
"webhook_url": "https://my_site.com/palenca_webhook",
"data": {
"webhook_action": "user.created",
"user_id": "da3fe164-3b65-44f6-99e5-c3ebab941481",
"account_id": null,
"country": null,
"platform": null
}
}

user.deleted

{
"webhook_url": "https://my_site.com/palenca_webhook",
"data": {
"webhook_action": "user.deleted",
"user_id": "cc821a8e-9640-4994-9e7c-c8efe43d608c",
"account_id": null,
"country": null,
"platform": null
}
}

profile.updated

{
"webhook_url": "https://my_site.com/palenca_webhook",
"data": {
"webhook_action": "profile.updated",
"user_id": "125bfab8-e127-3b6f-be24-f3301958d44e",
"account_id": "20948fdc-6645-3b6f-bb78-a41a609f7cee",
"external_id": "4707511",
"country": "mx",
"platform": "imss",
"status_details": null,
"curp": "MENR731930HDFJNJ01"
}
}

earnings.updated

{
"webhook_url": "https://my_site.com/palenca_webhook",
"data": {
"webhook_action": "earnings.updated",
"user_id": "125bfab8-e127-3b6f-be24-f3301958d44e",
"account_id": "20948fdc-6645-3b6f-bb78-a41a609f7cee",
"country": "pe",
"platform": "uber",
"status_details": null,
"phone": "555555555",
"recovered_earning_days": 49
}
}

earnings.updated

{
"webhook_url": "https://my_site.com/palenca_webhook",
"data": {
"webhook_action": "earnings.updated",
"user_id": "125bfab8-e127-3b6f-be24-f3301958d44e",
"account_id": "20948fdc-6645-3b6f-bb78-a41a609f7cee",
"external_id": null,
"country": "pe",
"platform": "cabify",
"status_details": null,
"email": "some-email@hotmail.com"
}
}

employment.updated

{
"webhook_url": "https://my_site.com/palenca_webhook",
"data": {
"webhook_action": "employment.updated",
"user_id": "125bfab8-e127-3b6f-be24-f3301958d44e",
"account_id": "20948fdc-6645-3b6f-bb78-a41a609f7cee",
"external_id": null,
"country": "mx",
"platform": "imss",
"status_details": null,
"curp": "MENR731930HDFJNJ01",
"employment_history_status": "complete",
"time_elapsed": 25
}
}

login.created

{
"webhook_url": "https://my_site.com/palenca_webhook",
"data": {
"webhook_action": "login.created",
"user_id": "125bfab8-e127-3b6f-be24-f3301958d44e",
"account_id": "20948fdc-6645-3b6f-bb78-a41a609f7cee",
"external_id": null,
"country": "pe",
"platform": "indriver",
"status_details": "pending_for_data",
"phone": "555555555"
}
}

login.success

{
"webhook_url": "https://my_site.com/palenca_webhook",
"data": {
"webhook_action": "login.success",
"user_id": "125bfab8-e127-3b6f-be24-f3301958d44e",
"account_id": "20948fdc-6645-3b6f-bb78-a41a609f7cee",
"external_id": null,
"country": "mx",
"platform": "imss",
"status_details": null,
"curp": "MENR731930HDFJNJ01"
}
}

login.error

{
"webhook_url": "https://my_site.com/palenca_webhook",
"data": {
"webhook_action": "login.error",
"user_id": "125bfab8-e127-3b6f-be24-f3301958d44e",
"account_id": "20948fdc-6645-3b6f-bb78-a41a609f7cee",
"external_id": null,
"country": "mx",
"platform": "imss",
"status_details": "service_degradation",
"curp": "MENR731930HDFJNJ01"
}
}

login.incomplete

{
"webhook_url": "https://my_site.com/palenca_webhook",
"data": {
"webhook_action": "login.error",
"user_id": "125bfab8-e127-3b6f-be24-f3301958d44e",
"account_id": "20948fdc-6645-3b6f-bb78-a41a609f7cee",
"external_id": null,
"country": "mx",
"platform": "issste",
"status_details": "curp_not_in_platform",
"curp": "MENR731930HDFJNJ01"
}
}

Eventos deprecados

Los siguientes eventos han sido deprecados ya que al ser enviados no garantizan que la información del trabajador esté lista para ser consultada a través de nuestra API.

Account

  • account.created
  • account.warning
  • account.needs_auth

Profile

  • profile.created

Login

  • login.retry
  • login.failed_refresh

Employment

  • employment.created

Gig

  • earnings.created
  • events.created