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.
Stage:
plain
34.226.254.178, 44.198.3.59, 34.223.185.46, 100.20.205.117
Prod/Sandbox:
plain
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: