Configure webhooks

We'll show you how to use our webhooks to receive real-time notifications.

At Pomelo we use webhooks to inform you about the main events that affect your operation. Each time these events occur, we make a `POST` request to an HTTPS endpoint on your server using a JSON object with the information.

How to configure a webhook

Step 1: Create your endpoint

You must create an endpoint on your server that meets these requirements:

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

Step 2: Recognize our IPs

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

• Testing/Staging Environment:
  34.226.254.178
44.198.3.59
34.223.185.46
100.20.205.117
  

• Production Environment:
  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 the requests we send you using hmac-sha256 so you can be certain they are from us. During the onboarding process, we will share an `api-key` and `api-secret` with you as explained in Key Exchange.

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

• x-api-key: will allow you to identify which `api-secret` to use (in case multiple `api-key` and `api-secret` pairs have been configured).

• x-signature: contains the digital signature (timestamp + endpoint + body) that you will need to validate to ensure the integrity of the request. We generate it using the `api-secret` that we previously shared with you. If the signature doesn't match, you should reject the request.

• x-timestamp: contains the moment when the request was signed in unix-epoch format so you can regenerate the signature and verify that it is valid. In the case of Authorize transaction, it will also allow you to validate that the signature has not expired (they expire after 1 minute).

• x-endpoint: is the endpoint to which the request is made and that we use to generate the signature. You must use this header to regenerate the signature to validate, compare it with your service endpoint, and verify that they match.

Below we show you an example of how to verify the validity of the signature:

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 allow you to identify which api-secret you need to use in case multiple api-key and api-secret pairs have been configured.

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

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

• x-endpoint: the endpoint to which the request is made and that was used to generate the signature. Use this header to regenerate the signature to validate, compare it with your service endpoint, and verify that they match.

Step 5: Response for cases that don't require signature

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