Webhooks (Deprecated)
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 |
---|---|
complete | Se pudo extraer todo el historial de empleo de un trabajador. Este valor solo se envía para casos del IMSS. |
null | Aú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"
}
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.
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