Webhook events are triggered when certain actions occur in your account such as order creation,buyer creation, etc. You can use these events to build custom integrations or automate your workflows.

​
Format

  • Webhooks are configured separately for sandbox and production environments.
  • The URL must be in the standard format of https://domain.com/path and must have a valid SSL certificate.
  • Wizcommerce will send a POST request to the URL with a JSON body and headers.
  • The request body will contain the event data in JSON format.
  • The request headers will contain the Content-Type header with the value application/json and the X-Wizcommerce-Signature header with the value of the signature.
  • The signature is a base64 encoded HMAC-SHA256 hash of the request body using the secret key as the key.

​
Security

  • The secret key is used to verify the authenticity of the request.
  • The secret key is used to generate the signature.
  • The signature is used to verify the authenticity of the request.
  • The secret key is not accessible to the external world.

​
Signature verification

Using the secret from API credentials, you can validate that the webhook is from Wizcommerce. This step is optional but recommended. The secret should never be exposed publicly. The X-Wizcommerce-Signature header included in each webhook request contains signature in a string. 
X-Wizcommerce-Signature: "<signature-1>,<signature-2>"
This signature is calculated using HMAC with the SHA256 algorithm, with your secret set as the key and the webhook request hashed body as the message. You can validate the webhook signature using an HMAC as shown below. In case of multiple signatures, you would expect to match at least one signature using at least one active secret. 
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"log"
)

// VerifyWebhookSignature validates the webhook signature using HMAC-SHA256
func VerifyWebhookSignature(webhookSecret, webhookBody, receivedSignature string) bool {
	// Create HMAC-SHA256 hash using the secret key
	h := hmac.New(sha256.New, []byte(webhookSecret))
	h.Write([]byte(webhookBody))
	expectedSignature := hex.EncodeToString(h.Sum(nil))

	// Perform a constant-time comparison to prevent timing attacks
	return hmac.Equal([]byte(expectedSignature), []byte(receivedSignature))
}

​
IP verification

Wizcommerce webhooks are sent from a specific IP range. You can whitelist these IPs to ensure that only Wizcommerce webhooks are processed. 
192.168.1.1
192.168.1.2

​
Timeouts

Wizcommerce webhooks are sent with a timeout of 30 seconds. If the webhook does not respond within 30 seconds, it will be considered failed.

​
Retry Mechanism

To avoid an event being missed, Wizcommerce follows at-least-once delivery semantics. In this approach, if we do not receive a successful response from your server (non 200 HTTP status) or we get a timeout, we resend the webhook. Success status codes are 200, 201, 202, 204. We use exponential backoff to retry the webhook. One event will be retried at most 5 times. Example retry schedule:
  • 1st retry: 30 seconds
  • 2nd retry: 1 minute
  • 3rd retry: 2 minutes
  • 4th retry: 4 minutes
  • 5th retry: 8 minutes (total 15 minutes)

​
Idempotency

In cases of failure (response with non 200 HTTP status) or timeout, it is assumed that the webhook has not been processed and is sent again as per the retry policy. Ensure your server is configured to handle or receive the same event details multiple times. To help with this, we provide a unique id with all our webhook payloads. Using these IDs, you can dedupe at your end in case of a doubt, or even report errors to/request support from us easily.

​
Delivery semantics

Usually, webhook events are delivered within a few seconds of the associated event. However, this can be delayed by a few minutes in some cases due to various reasons. While we try to send them promptly, we do not recommend relying on webhooks for time-sensitive events. For business-critical, synchronous use cases, we recommend using the Webhooks API instead.