Webhooks (Deprecated)

info

Webhooks are especially useful so that you can correctly implement our API, since the time it takes to extract the data varies by platform and ranges between 10 and 40 seconds.

By implemented correctly, you will be able to automatically activate processes in your backend that depend on worker income data.

For example, receiving the employment.updated event means that the employment data is available and you can trigger a GET request in your backend to the endpoint /accounts/:account_id/employment

Introduction

A webhook is the way Palenca communicates with your application. It is achieved through a URL that you provide us to which we send notifications/events to keep you updated on your users' connections. These events are sent in JSON format, allowing you to automatically trigger processes in your backend.

Every time an event is generated, you can see them in the Console within the Webhooks section.

Implementation

To register a webhook in Palenca you must follow these steps:

Go to the "Developers" section within the Console;
Open the "Webhooks" tab;
Click on "Create Webhook";
Register the webhook URL (you can use a tool like webhook.site to test). You must associate the webhook with a specific widget or with all connections generated via API (IMSS & ISSSTE);
Click on "Confirm".
Share the link of the widget to test some connections or make IMSS & ISSSTE connections through our API and validate that the events are received at the URL you registered.

Data Schema of an Event

The generic data schema of an event that we notify via webhook is the following:

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

Some events will include additional information that we will detail later in the New Fields section.

Event example

The data you will receive from Palenca will include information about the user or account and the triggered webhook action.

Next, an example of the event we send to your URL is shown:

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

Event list

In the following table you can see all the events we send. We recommend you visit our [Entities] section (docs/v2/Guides/ApiConcepts/Entities.md) for more information.

Event	Category	Description
`user.created`	User	A user has been successfully created.
`user.deleted`	User	A user has been successfully deleted.
`profile.updated`	Profile	Account profile information has been created or updated and can be viewed through our API.
`earnings.updated`	Earnings	Account earnings information has been created or updated and can be viewed through our API.
`events.updated`	Events	Account event information has been created or updated and can be viewed through our API.
`employment.updated`	Employment	Account employment information has been created or updated and can be viewed through our API.
`login.created`	Login	The user has started the authentication process on an account.
`login.success`	Login	The user has successfully logged in to her account and the data extraction process has started. Please note that once the login is successful, the user must wait 12 hours to log in again.
`login.error`	Login	The user could not successfully connect to her account. Please contact our support team.
`login.incomplete`	Login	The user did not complete the authentication process. This event will ONLY be sent if more than 500 seconds have passed and the user has not successfully completed the login flow.

New Fields

Currently there are two events, employment.updated and earnings.updated, which as of March 2024 will return additional information extending the base schema.

As of March 2024, the employment.updated event will have two new fields within data:

1. employment_history_status: Refers to the status of the extraction process of a worker's employment history affiliated with IMSS or ISSSTE by Palenca. This field can take the following values:

Key	Definition
complete	The entire employment history of a worker could be extracted. This value will only be sent for IMSS scenarios.
null	There is not enough information yet to determine the status of the process. For ISSSTE scenario. is the event is employment.updated then the extraction information could be done

2. time_elapsed: The approximate number of seconds elapsed between the creation of the login and the retrieval of employment data. This field could have a null value if the employment extraction process was not completed. It is important to emphasize that this is only an approximation. It is difficult to give the exact figure given the asynchrony of the data extraction processes.

Next, an example of the event we send including the additional data is shown below:

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

Similarly, the earnings.updated event will have a new field within data:

1. recovered_earning_days: Refers to the number of days where non-zero earnings were recovered for a worker. This field is numeric.

Next, an example of the event we send including the additional data is shown below:

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

Retries

If we do not receive a 200 or 201 code within 30 seconds of the first POST request to the webhook URL, We will make up to three additional calls (stopping if we get a 200 or 201 code), waiting a ~30s between each call.

Important

If after 3 attempts we do not receive a 200 or 201 code, we will stop sending the event to your URL and the webhook will be disabled. You can request our support team to re-enable it after you fix the underlying issue. We do not buffer the webhooks while disabled.

Event samples:

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

Deprecated events

The following events have been deprecated since when sent they do not guarantee that the worker's information is ready to be consulted through our 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 (Deprecated)

Introduction​

Implementation​

Data Schema of an Event​

Event example​

Event list​

New Fields​

Retries​

Event samples:​

user.created​

user.deleted​

profile.updated​

earnings.updated​

earnings.updated​

employment.updated​

login.created​

login.success​

login.error​

login.incomplete​

Deprecated events​

Account​

Profile​

Login​

Employment​

Gig​

Introduction

Implementation

Data Schema of an Event

Event example

Event list

New Fields

Retries

Event samples:

user.created

user.deleted

profile.updated

earnings.updated

earnings.updated

employment.updated

login.created

login.success

login.error

login.incomplete

Deprecated events

Account

Profile

Login

Employment

Gig