Webhooks

Nuevos campos

A partir de marzo de 2024 algunos eventos contendrán información adicional. Más info aquí.

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.

Implementación

Para registrar un webhook en Palenca debes seguir estos pasos:

Ve a la sección de "Desarrolladores" dentro de la Consola.
Abre la pestaña de "Webhooks".
Da click en "Crear Webhook", esto abrira un modal con el formulario para dar de alta un nuevo webhook.
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).
Selecciona los eventos de los que deseas recibir notificaciones.
Da click en "Crear Webhook".
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.

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.

Evento	Categoría	Descripción
`user.created`	Usuario	Se ha creado exitosamente un usuario.
`user.deleted`	Usuario	Se ha borrando exitosamente un usuario.
`profile.updated`	Perfil	Se ha creado o actualizado la información del perfil de la cuenta y puedes consultarla a través de nuestra API.
`earnings.updated`	Ganancias	Se ha creado o actualizado la información de ganancias de la cuenta y puedes consultarla a través de nuestra API.
`events.updated`	Eventos	Se ha creado o actualizado la información de eventos de la cuenta y puedes consultarla a través de nuestra API.
`employment.updated`	Empleo	Se ha creado o actualizado la información de empleo de la cuenta y puedes consultarla a través de nuestra API.
`login.created`	Inicio de sesión	El usuario ha iniciado el proceso de autenticación en una cuenta.
`login.success`	Inicio de sesión	El 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.error`	Inicio de sesión	El usuario no pudo conectarse exitosamente a su cuenta. Por favor, comunícate con nuestro equipo de soporte.
`login.incomplete`	Inicio de sesión	El 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:

Clave	Definición
empty	El usuario no tiene historial de empleo (ejemplo, no tiene semanas cotizadas)
partial	Solo se ha podido extraer una parte del historial de empleo (ejemplo, RPCI en IMSS)
complete	Se pudo extraer todo el historial de empleo de un trabajador
null	Aún no hay información suficiente para determinar el estatus del proceso

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 de la primera solicitud POST a la URL del webhook, realizaremos hasta tres llamadas adicionales (deteniéndonos si obtenemos un código 200 o 201), esperando unos minutos 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.

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.retry
login.failed_refresh

Employment

employment.created

Gig

earnings.created
events.created

Webhooks

Introducción​

Implementación​

Esquema de datos de un evento​

Ejemplo de evento​

Lista de eventos​

Campos nuevos​

Reintentos​

Ejemplos de eventos:​

user.created​

user.deleted​

profile.updated​

earnings.updated​

earnings.updated​

employment.updated​

login.created​

login.success​

login.error​

login.incomplete​

Eventos deprecados​

Account​

Profile​

Login​

Employment​

Gig​

Introducción

Implementación

Esquema de datos de un evento

Ejemplo de evento

Lista de eventos

Campos nuevos

Reintentos

Ejemplos de eventos:

user.created

user.deleted

profile.updated

earnings.updated

earnings.updated

employment.updated

login.created

login.success

login.error

login.incomplete

Eventos deprecados

Account

Profile

Login

Employment

Gig