Webhooks (New)

Cambios a Webhook

A partir de Diciembre de 2024 reduciremos nuestros tipos de eventos de webhook. 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 180 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 login.success 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": {
      "webhook_id": "some string",
    "account_id": "some string",
    "external_id": [
      "string",
      "null"
    ],
    "platform": "some string",
    "user_id": "some string",
    "status_details":"some string",
    "webhook_action": "some string"
  },
  "webhook_url": "uri"
}

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": {
        "webhook_id": "f393ce50-d8db-43a1-83da-a2d45b5dee50",
         "account_id": "6fdf1c40-503b-11ef-88d3-6d05baf28f03",
         "external_id": "1234567890",
         "platform": "imss",
        "user_id": "829462f0-503b-11ef-88d3-6d05baf28f03",
        "status_details":"service_degradation",
        "webhook_action": "login.error"
  },
  "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	Descripción
`login.created`	1. Indica que se ha creado un inicio de sesión. 2. Esto debería activarse tan pronto como creemos un registro dentro de la tabla 'logins'.
`login.error`	1. Indica que el estado de un inicio de sesión se ha actualizado a `error`. Este es un estado final. 2. Esto debería activarse tan pronto como el estado del inicio de sesión en la tabla 'logins' se actualice a 'error'.
`login.incomplete`	1. Indica que el estado de un inicio de sesión se ha actualizado a `incompleto`. Este es un estado final. 2. Esto debería activarse tan pronto como el estado del inicio de sesión en la tabla 'logins' se actualice a 'incompleto'.
`login.success`	1. Para plataformas de empleo, esto indica que se ha creado un registro dentro de la tabla `employment` para una cuenta específica. - Esto debería activarse tan pronto como creemos un registro dentro de la tabla `employment`. 2. Para una plataforma de trabajo por encargo, esto indica que se ha creado un registro dentro de la tabla `earnings` para una cuenta específica. - Esto debería activarse tan pronto como creemos un registro dentro de la tabla `earnings`.

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.

Ejemplos de eventos:

login.created

{
  "data": {
        "webhook_id": "f393ce50-d8db-43a1-83da-a2d45b5dee50",
    "account_id": "6fdf1c40-503b-11ef-88d3-6d05baf28f03",
    "external_id": "1234567890",
    "platform": "imss",
    "user_id": "829462f0-503b-11ef-88d3-6d05baf28f03",
    "status_details":null,
    "webhook_action": "login.created"
  },
  "webhook_url": "https://my_site.com/palenca_webhook"
}

login.incomplete

{
  "data": {
        "webhook_id": "f393ce50-d8db-43a1-83da-a2d45b5dee50",
    "account_id": "6fdf1c40-503b-11ef-88d3-6d05baf28f03",
    "external_id": "1234567890",
    "platform": "imss",
    "user_id": "829462f0-503b-11ef-88d3-6d05baf28f03",
    "status_details":"curp_has_inconsistencies",
    "webhook_action": "login.incomplete"
  },
  "webhook_url": "https://my_site.com/palenca_webhook"
}

login.error

{
  "data": {
        "webhook_id": "f393ce50-d8db-43a1-83da-a2d45b5dee50",
    "account_id": "6fdf1c40-503b-11ef-88d3-6d05baf28f03",
    "external_id": "1234567890",
    "platform": "imss",
    "user_id": "829462f0-503b-11ef-88d3-6d05baf28f03",
    "status_details":"service_degradation",
    "webhook_action": "login.error"
  },
  "webhook_url": "https://my_site.com/palenca_webhook"
}

login.success

{
  "data": {
    "webhook_id": "f393ce50-d8db-43a1-83da-a2d45b5dee50",
    "account_id": "6fdf1c40-503b-11ef-88d3-6d05baf28f03",
    "external_id": "1234567890",
    "platform": "imss",
    "user_id": "829462f0-503b-11ef-88d3-6d05baf28f03",
    "status_details":null
    "webhook_action": "login.success"
  },
  "webhook_url": "https://my_site.com/palenca_webhook"
}

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.

User

user.created
user.deleted

Account

account.created
account.warning
account.needs_auth

Profile

profile.created
profile.updated

login.retry
login.failed_refresh

Employment

employment.created
employment.updated

Gig

earnings.created
earnings.updated
events.created

Webhooks (New)

Introducción​

Implementación​

Esquema de datos de un evento​

Ejemplo de evento​

Lista de eventos​

Reintentos​

Ejemplos de eventos:​

login.created​

login.incomplete​

login.error​

login.success​

Eventos deprecados​

User​

Account​

Profile​

Login​

Employment​

Gig​