Webhooks & Signature Verification

Shopier dispatches event notifications via HTTP POST to your configured Notification URL. To guarantee authenticity and prevent tampering, every webhook payload is signed with HS256 (HMAC-SHA256) using your app's webhook secret token.

---

Webhook Headers

Header	Description
Shopier-Signature	HMAC-SHA256 signature string (hex or base64)
Shopier-Event	Event type identifier (e.g., order.created)
Shopier-Webhook-Id	Unique ID of the notification event
Shopier-Timestamp	Unix timestamp in seconds (UTC)
Shopier-Account-Id	The shop account ID associated with the event
Shopier-Api-Version	API version string

---

Supported Events

Event Constant	Event Name	Payload Model	Trigger Scenario
webhook.EventOrderCreated	order.created	*shopier.Order	A new order is paid and placed
webhook.EventOrderAddressUpdated	order.addressUpdated	*shopier.Order	Buyer shipping address is updated
webhook.EventOrderFulfilled	order.fulfilled	*shopier.Order	Order is closed and marked shipped
webhook.EventProductCreated	product.created	*shopier.Product	A new product listing is published
webhook.EventProductUpdated	product.updated	*shopier.Product	An existing product is updated
webhook.EventRefundRequested	refund.requested	*shopier.Refund	A seller requests an order refund
webhook.EventRefundUpdated	refund.updated	*shopier.Refund	Refund succeeds or fails

---

Webhook Event Models

webhook.Event

type Event struct {
	Header     Header // HTTP header metadata
	RawPayload []byte // Raw unparsed JSON payload
}

Helper Methods:

• evt.Order() -> (*shopier.Order, error): Parses payload into shopier.Order.
• evt.Product() -> (*shopier.Product, error): Parses payload into shopier.Product.
• evt.Refund() -> (*shopier.Refund, error): Parses payload into shopier.Refund.

webhook.Header

Field	Type	Header Key	Description
WebhookID	string	Shopier-Webhook-Id	Unique notification identifier
Event	string	Shopier-Event	Event identifier (e.g. order.created)
Timestamp	int64	Shopier-Timestamp	Event dispatch time in Unix seconds (UTC)
Signature	string	Shopier-Signature	HMAC-SHA256 signature string
AccountID	string	Shopier-Account-Id	Associated Shopier shop account ID
APIVersion	string	Shopier-Api-Version	API version string

---

1. Using the Built-in http.Handler Adapter

The fastest way to mount a production-ready webhook endpoint in Go:

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"

	"github.com/AdisGroup/shopier-go/webhook"
)

func main() {
	secret := os.Getenv("SHOPIER_WEBHOOK_SECRET")

	handler := webhook.NewHandler(secret, func(ctx context.Context, evt *webhook.Event) error {
		log.Printf("Received event: %s (ID: %s)", evt.Header.Event, evt.Header.WebhookID)

		switch evt.Header.Event {
		case webhook.EventOrderCreated:
			order, err := evt.Order()
			if err != nil {
				return err
			}
			fmt.Printf("New Order #%s for %s %s\n", order.ID, order.Totals.Total, order.Currency)

		case webhook.EventRefundRequested:
			refund, err := evt.Refund()
			if err != nil {
				return err
			}
			fmt.Printf("Refund requested: #%s (Order: %s)\n", refund.ID, refund.OrderID)
		}

		return nil
	})

	http.Handle("/webhooks/shopier", handler)
	log.Fatal(http.ListenAndServe(":8080", nil))
}

---

2. Manual Verification in Web Frameworks (Gin, Chi, Fiber)

Standard webhook.Parse

You can verify and parse any *http.Request directly:

event, err := webhook.Parse(r, webhookSecret)
if err != nil {
	http.Error(w, "Unauthorized: "+err.Error(), http.StatusUnauthorized)
	return
}

order, _ := event.Order()

Direct Byte Verification (webhook.VerifySignature)

For frameworks like Fiber that do not expose standard *http.Request:

// Fiber example
app.Post("/webhooks/shopier", func(c *fiber.Ctx) error {
	sig := c.Get("Shopier-Signature")
	body := c.Body()

	if !webhook.VerifySignature(body, sig, webhookSecret) {
		return c.Status(fiber.StatusUnauthorized).SendString("Invalid signature")
	}

	// Process payload...
	return c.SendStatus(fiber.StatusOK)
})