Webhook Documentation

To receive real-time notifications about orders, register your webhook by sending a request to our Webhooks endpoint (see endpoint reference). Once configured, we'll generate a secret token and include it in the response. This token will be used to generate the signature included in each webhook request, allowing you to verify integrity and autenticity of the request.

Registering Your Webhook Endpoint

To register (or update) your webhook endpoint, make a POST request to: https://{environment}.nelo.co/v1/admin/webhooks

Authentication

Your store is associated with your webhook via the API token you received during onboarding. Include it in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN 

Request Body

Your request body should include the URL for your webhook endpoint. (For the full request schema, please refer to our Webhook API Reference )

Response

On successful registration, the response will include a single field: webhook_secret. A secret token used to sign the webhook payloads.

Example response:

{  
  "webhook_secret": "token"  
}

Note: Every time you POST to this endpoint, your previous webhook configuration is replaced with the new one.

Signature Verification

Each webhook event request sent to your registered endpoint includes a signature in the x-signature header and a timestamp in the x-signature-timestamp header. This signature is generated using your webhook_secret with HMAC-SHA256.

Digest Composition

For every webhook event, the signature digest is composed using the following string format:

"id:$orderId;status:$orderStatus;ts:$timestamp"

Where:

• orderId is the unique identifier of the order.
• orderStatus is the current status of the order.
• timestamp is an epoch provided with every webhook event request.

Example Signature Verification Flow

1. Receive the webhook event request which includes:

• The payload containing order details (id, status, etc.).
• The x-signature-timestamp header with an epoch value.
• The x-signature header with the HMAC signature.

2. Recreate the digest string using the values from the payload "$orderId;status:$orderStatus;ts:$timestamp"
3. Generate an HMAC signature using the webhook_secret and HMAC-SHA256 algorithm.
4. Compare the computed signature with the x-signature header to verify the authenticity of the request.
5. [Optional] Timestamp validation To further secure your webhook endpoint, enforce validation on the timestamp. Reject any request if the timestamp is in the future or if it is older than 30 seconds compared to your server time. This helps mitigate replay attacks by ensuring that each request is fresh. If we need to resend any event for any reason, we will get a fresh timestamp and signature.

For further endpoint details, please refer to our Webhook API Reference.

Happy integrating!