Webhooks General Guide

1. Definitions

Webhook

Webhooks are user-defined HTTP callbacks which receive events for the types of events to which they are subscribed. Webhooks are asynchronous, order is not guaranteed and idempotency can lead to the same result when sent more than once. Webhooks settings include enable and disable.

Event

Events are classified into event types. Events are caused by changes in the status of a resource, such as when a payment changes from registered to completed. When an event occurs, Pagadito notifies through an HTTP POST request on the registered Webhook. The POST contains the Details of the event and the entire resource, including the type of event that gave way to such event.

Types of Events

The types of events are the different triggers that take place in a Pagadito Merchant account, such as a payment that is completed.

2. Configuring Webhooks

To use Webhooks in Sandbox or production, do the following:

1. Go to the dashboard of your Pagadito Merchant account
2. Go to Webhooks in the Technical Settings section.
3. Enable notifications to be sent via Webhooks.
4. Add the WEBHOOK URL.
5. Save the Webhooks settings.

Once saved, a successfully configured Webhook message will appear, and you will be able to see the URL of your Webhook.

3. Types of Events

Event types are the different triggers that happen in a Pagadito Merchant account, such as a completed payment.

Supported Event Types

The currently supported event types are as follows:

• TRANSACTION.STATUS.CHANGE: This event is triggered when a payment is recorded, also when a payment changes status to completed, verified, rejected, and expired.

4. Events

Events are notifications that are sent to the Webhook URL for specific triggers in the Pagadito Merchant account, such as a completed payment.

Event Information

When an event occurs, Pagadito sends the JSON-encoded event information using an HTTP POST to the application at the URL you specified. If the application is not available or takes too long to respond (a timeout occurs), Pagadito cancels the request and retries twenty times for a period of 3 days.

The parameter event_type in the message indicates the trigger for the event.

Event Security

Each of the events sent to the applications are signed.

Event Signature

Since theoretically anyone could send an HTTP POST to your application, it is important to verify that:

• The Webhook event originated from Pagadito.
• The Webhook event was not altered/corrupted during transmission.
• The Webhook event was in fact directed to the recipient.

Therefore, Webhook events will contain a header containing a signature of the message. The recipient of the Webhook event can optionally validate that signature.

Events are signed and delivered as a message over HTTP. The following headers are used to provide information for signature validation.

• PAGADITO-SIGNATURE specifies the asymmetric signature generated by Pagadito encoded in Base 64.
• PAGADITO-AUTH-ALGO specifies the algorithm used to generate and verify the asymmetric signature.
• PAGADITO-CERT-URL specifies the URL address to download the X509 public key certificate to be used in the verification process.

The signature is generated by concatenating five different parts with a | (vertical bar) as a separator between the parts. The details of the individual parts are as follows:

• Notification ID: Unique identifier of the HTTP notification. Contained in the PAGADITO-NOTIFICATION-ID header of the Webhook event.
• Timestamp Notification: Notification of the HTTP Timestamp. Contained in the PAGADITO-NOTIFICATION-TIMESTAMP header of the Webhook event.
• Event ID: This is the id of the Webhook event that is delivered in the event body.
• Cyclic Redundancy Check (CRC32): CRC32 checksum for the HTTP request body.
• WSK: Web Service Key of the Pagadito Merchant account, this data can be found in the panel of your Pagadito Merchant account, go to Integration Parameters in the Technical Configuration section, in the Connection Credentials section.

Thus, the input string to validate the signature would have the following form: IdNotificacion|TimestampNotificacion|IdEvento|CRC32|WSK

The authentication algorithm specified in PAGADITO-AUTH-ALGO uses an asymmetric signature algorithm. This allows Pagadito to use a private key to create the signature in PAGADADITO-SIGNATURE, while allowing you to use a public key contained in the certificate whose path is defined in PAGADITO-CERT-URL to verify the Webhook event.

The following PHP code combines the headers and input string to perform the verification.

Event Response

When an application receives the event, it must respond with a level 200 HTTP status code. If it responds with any other response code, Pagadito will keep on trying to deliver the event twenty times over a 3-day period.