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:

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.



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:

Did you find the content of this document helpful?