Setting up webhooks

Get to know how to use our webhooks to get notifications in real-time.

At Pomelo, we use webhooks to notify you about the main events that impact on your operation:

• When a payment transaction is initiated (CARDS)
• If an adjustment to an existing transaction is made (CARDS)
• When the status of a transaction is resolved (CARDS)
• Each time a shipment status is modified(CARDS)
• When an activity is created or updated (DIGITAL ACCOUNTS)
• When a user's identity is validated (IDENTITY)

Whenever those events occur, we make a POST request to an HTTPS endpoint on your server using a JSON object with the information.

How to set up a webhook

Step 1: Create your endpoint

Start by creating an endpoint on your server that meets the following requirements:

• Receive traffic over HTTPS
• Receive a JSON object in the request body

Step 2: Recognize our IPs

We always communicate with you from our own specific IPs. We recommend that you only accept requests from one of our IPs and reject any other addresses.

• Testing/Staging:
  34.226.254.178
  44.198.3.59
  34.223.185.46
  100.20.205.117
  

• Prod:
  34.206.159.176
  52.0.20.124
  35.84.78.117
  52.43.46.111
  

Step 3: Validate our signature

As a security measure, we sign all the requests we send with hmac-sha256, so you can be sure they come from us. During the onboarding process, we will share with you an api-key and an api-secret, as explained in the Keys exchange.

In each request, we send HTTP headers that will allow you to verify that the signature is correct:

• x-api-key: this header will allow you to identify the specific api-secret to use (in cases where multiple api-key and api-secret pairs have been configured).

• x-signature: contains the digital signature (body + timestamp + endpoint) that you must validate to ensure the request’s integrity. We generate the signature using the api-secret that we have previously shared with you. If the signatures don’t match, you must reject the request.

• x-timestamp: indicates the time the request was signed in unix-epoch format, allowing you to regenerate the signature and verify its validity. Regarding the Authorize transaction, it will also enable you to validate that the signature has not expired yet (they expire after 1 minute).

• x-endpoint: is the endpoint that created the request and the one we use to generate the signature. You should use this header to regenerate the signature to be validated, compare it with the endpoint of your service and verify that they match.

The following is an example of how to verify the signature’s validity:

See other examples

Step 4: Response signature (only for authorizing transactions)

To authorize transactions, we will also ask you to sign the response.

The HTTP headers you must send are:

• x-api-key: this header will help you identify which api-secret you need to use in case multiple api-key and api-secret pairs are configured.

• x-signature: this header contains the digital signature (body + timestamp + endpoint) that you must verify to ensure the integrity of the request. If the signature does not match, you must reject the request.

• x-timestamp: this header contains the time the request was signed in unix-epoch format so that you can verify if the signature has expired.

• x-endpoint: the endpoint to which the request is made and used to generate the signature. Use this header to regenerate the signature for validation, compare it with your service's endpoint, and ensure they match.

Implementation examples for request validation and signature

In our repository, you will find implementation examples of the signature generation and validation algorithm in various languages. See repository

Step 4: Response for cases that do not require a signature

We expect a 2XX type response to ensure you received the notification. Otherwise, we will try again.