HTTPS webhook delivery

Webhooks allow your application to receive information about order events as they occur and respond in a way that you define. This documentation will detail configuring and testing webhooks, as well as information about authentication.

1. Register an endpoint

Your endpoint must be an HTTPS webhook address that can receive POST requests and process JSON payloads. Contact iAsig.md to become a partner, and provide us the webhook url.

2. Verify the endpoint

Every webhook request sent to your provided endpoint will include a special X-Hmac-Signature header. This header contains your Partner ID and an HMAC signature. The HMAC signature is generated using the HMAC SHA512 algorithm and your unique, secret API key (provided by iAsig.md).

When you receive a webhook request, follow these steps:

1. Recalculate the HMAC signature using your secret API key and the received JSON data.
2. Compare your calculated signature to the value in the X-Hmac-Signature header.
3. If the values match, you can trust that the notification genuinely came from iAsig.md.

Important: Requests without a valid X-Hmac-Signature should be rejected.

const express = require('express');
const crypto = require('crypto');

const app = express();
const PORT = process.env.PORT || 4000;

// Secret key and partner ID
const secret = '...';
const partnerId = '...';

// Function to verify webhook signature
function verifyWebhook(body, hmacHeader) {
  const theSecret = Buffer.from(secret);

  const hash = crypto.createHmac('sha512', theSecret).update(body).digest('hex');
  const computedSignature = `${partnerId}:${hash}`;

  return computedSignature === hmacHeader;
}

// Endpoint to receive webhook notifications
app.post('/your-webhook-endpoint', (req, res) => {
  const data = req.body; //The payload content
  const hmacHeader = request.headers['x-hmac-signature'][0];

  const verified = verifyWebhook(data, hmacHeader);

  if (!verified) {
    return res.status(401).send('Unauthorized');
  }

  // Process webhook payload
  // ...

  return res.sendStatus(200);
});

const server = app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

This code was used to test the HMAC signature. It may require changes depending on the used services.

3. The endpoint payload

This webhook notifies subscribed endpoints whenever an order's status changes to completed. It sends a JSON payload containing information about the order, including its ID and status.

{
  "orderId": "ROV000001ABC",
  "status": "completed"
}

4. Respond to the webhook

Your webhook acknowledges that it received data by sending a 200 OK response. Any other response indicates that you didn't receive the webhook.

5. Retry frequency

We wait ten seconds for a response to each request to a webhook. If there's no response, or an error is returned, then we retry the connection 20 times over the next 48 hours.