Webhooks (New)

Webhook changes

Starting in December 2024, we will reduce our webhook event types. More info here.

info

Webhooks are especially useful for correctly implementing our API, as the time it takes to extract data varies by platform, ranging between 10 and 180 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 login.success event means that the employment data is available, and you can trigger a GET request to the /accounts/:account_id/employment endpoint from your backend.

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:

1. Go to the "Developers" section within the Console;

2. Open the "Webhooks" tab;

3. Click on "Create Webhook";

4. 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);

5. Click on "Confirm".

6. 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": {
      "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"
}

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

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	Description
login.created	1. Indicates that a login has been created. 2. This should be triggered as soon as a record is created in the 'logins' table.
login.error	1. Indicates that the status of a login has been updated to error. This is a final status. 2. This should be triggered as soon as the login status in the 'logins' table is updated to 'error'.
login.incomplete	1. Indicates that the status of a login has been updated to incomplete. This is a final status. 2. This should be triggered as soon as the login status in the 'logins' table is updated to 'incomplete'.
login.success	1. For employment platforms, this indicates that a record has been created in the employment table for a specific account. - This should be triggered as soon as a record is created in the employment table. 2. For gig platforms, this indicates that a record has been created in the earnings table for a specific account. - This should be triggered as soon as a record is created in the earnings table.

Retries

If we do not receive a 200 or 201 status code within 30 seconds after the first POST request to the webhook URL,
we will make up to three additional attempts (stopping if we receive a 200 or 201), waiting approximately ~30 seconds between each attempt.

Example Events:

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

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.

User

• user.created
• user.deleted

Account

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

Profile

• profile.created
• profile.updated

Login

• login.retry
• login.failed_refresh

Employment

• employment.created
• employment.updated

Gig

• earnings.created
• earnings.updated
• events.created