Webhooks

📘

Information

We strongly recommend enabling webhook notifications. Palenca’s data extraction processes vary by platform and can take anywhere from 10 to 180 seconds.

When properly implemented, webhooks allow you to automatically trigger backend processes that rely on workers’ income data.

Below, we provide use cases and examples to help you integrate webhook notifications successfully.

Introduction

Webhooks allow Palenca to communicate with your application. All you need to do is provide us with an URL to which we can send notifications (read, POST requests) to keep you updated on the status of your users' connections. The details of each event are sent in the request body in JSON format, allowing you to automatically trigger processes in your backend.

Let's jump right into creating your first webhook!

Create your first webhook

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

1. Log in to your Console account.
2. Go to the </> Developers section on the left side of your Console menu.
3. Open the Webhooks tab.
4. Click on the Create Webhook button.
5. Choose a name for your webhook and register its URL (you can use a tool like webhook.site to perform quick tests). You must associate the webhook with a specific widget. If you don't have one, you can easily create one in the Widgets section on the left side of your Console.
6. Choose the webhook events you want to listen to.
7. Click on Create webhook.
8. 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.

Note that you can see webhook events in the Console too. Just click on it and the following screen will appear.

Video Tutorial: Create and Test a Webhook in 5 minutes.

Here is a video tutorial showing you how to integrate Palenca webhooks in your API.

https://www.loom.com/share/870aab22dc8544b1a2568da712f98f36?sid=24a9b5df-3094-4604-a318-c4b37f539b8a

Data Schema of Webhook Events

We use a standardized data schema for webhook events:

{
   "data":{
      "webhook_id":"string",
      "account_id":"string",
      "external_id":"string | null",
      "platform":"string",
      "user_id":"string",
      "status_details":"string",
      "webhook_action":"event_category.event_type"
   },
   "webhook_url":"string"
}

Webhook Notification Example

Let's say you integrated webhook notifications and one of your IMSS connections encountered an error during login. Here is an example of the request body your API could receive:

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

Webhook Events Catalog

In the following table you can see all the events we send. We recommend you visit the Entities page for more details.

The following diagram can help you understand this better:

In other words, only the login.successwebhook event should trigger a request from your backend to our API.

Retries

If we do not receive a 200 or 201 status code within 30 seconds after the first POST request to your 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"
}

Webhooks for API-based worfklows.

In the tutorial we showed above, we mentioned that you need to associate a webhook with a widget_id.

You just need to send that widget_id in the create user and account endpoint and that's it!