shieldlabs

README

shieldlabs-go

ShieldLabs server SDK for Go: webhook verification, typed events, History API client.

import "github.com/ShieldLabs-ai/shieldlabs-go"

ok := shieldlabs.VerifyWebhook(rawBody, r.Header.Get("X-Shield-Signature"), secret)

Signature: X-Shield-Signature: sha256= + hex(HMAC-SHA256(secret, raw_body)). Schema 2026-06-01.

License

MIT

Documentation

Overview

Package shieldlabs is the ShieldLabs server SDK for Go: webhook verification, typed webhook events, and a History API client.

Your code decides what to do with the score. This SDK never makes the decision for you.

Index

• Constants
• func VerifyWebhook(payload []byte, signature, secret string) bool
• type Client
  • func New(apiKey string) *Client
  • func (c *Client) GetHistory(searchType, value string, limit, offset int) (*HistoryResponse, error)
• type HistoryResponse
• type WebhookDetectionFlags
• type WebhookEvent
• type WebhookIPAddress
• type WebhookScoredData
• type WebhookSignal
• type WebhookTrafficSource

Constants

const WEBHOOK_SCHEMA_VERSION = "2026-06-01"

WEBHOOK_SCHEMA_VERSION is the contract version emitted by Shield.Core.

Functions

func VerifyWebhook

func VerifyWebhook(payload []byte, signature, secret string) bool

VerifyWebhook checks X-Shield-Signature against HMAC-SHA256(secret, payload). Comparison is constant-time. payload must be the raw request body bytes.

Types

type Client

type Client struct {
	APIKey     string
	BaseURL    string
	HTTPClient *http.Client
}

Client talks to the History API on account.shieldlabs.ai.

func New

func New(apiKey string) *Client

New returns a History API client.

func (*Client) GetHistory

func (c *Client) GetHistory(searchType, value string, limit, offset int) (*HistoryResponse, error)

GetHistory calls GET /api/v1/history/{searchType}/{value}.

type HistoryResponse

type HistoryResponse struct {
	Data  []json.RawMessage `json:"data"`
	Total uint64            `json:"total"`
}

HistoryResponse is the {data, total} envelope from Portal.Admin.

type WebhookDetectionFlags

type WebhookDetectionFlags struct {
	VPN                 bool `json:"vpn"`
	PrivacyRelay        bool `json:"privacy_relay"`
	BrowserVpnProxy     bool `json:"browser_vpn_proxy"`
	Tor                 bool `json:"tor"`
	Proxy               bool `json:"proxy"`
	DatacenterIP        bool `json:"datacenter_ip"`
	Abuser              bool `json:"abuser"`
	OSMismatch          bool `json:"os_mismatch"`
	OSNotDetected       bool `json:"os_not_detected"`
	TimezoneMismatch    bool `json:"timezone_mismatch"`
	AntiDetectBrowser   bool `json:"anti_detect_browser"`
	BrowserAutomation   bool `json:"browser_automation"`
	IPMismatch          bool `json:"ip_mismatch"`
	Incognito           bool `json:"incognito"`
	SearchBot           bool `json:"search_bot"`
	SuspiciousPaidClick bool `json:"suspicious_paid_click"`
	JavascriptDisabled  bool `json:"javascript_disabled"`
	StunRequestSeen     bool `json:"stun_request_seen"`
	StunNotChecked      bool `json:"stun_not_checked"`
}

WebhookDetectionFlags matches Shield.Core entity.WebhookDetectionFlags.

type WebhookEvent

type WebhookEvent struct {
	EventType     string             `json:"event_type"`
	SchemaVersion string             `json:"schema_version"`
	CreatedAt     time.Time          `json:"created_at"`
	Data          *WebhookScoredData `json:"data,omitempty"`
}

WebhookEvent is the POST body envelope.

type WebhookIPAddress

type WebhookIPAddress struct {
	IP      string `json:"ip"`
	Country string `json:"country"`
}

WebhookIPAddress is an IP + country pair.

type WebhookScoredData

type WebhookScoredData struct {
	RequestID      string                `json:"request_id"`
	VisitorID      string                `json:"visitor_id"`
	DeviceID       string                `json:"device_id"`
	SessionID      string                `json:"session_id"`
	CookieID       string                `json:"cookie_id"`
	UserHID        *string               `json:"user_hid"`
	Domain         string                `json:"domain"`
	PublicIP       WebhookIPAddress      `json:"public_ip"`
	LocalIP        WebhookIPAddress      `json:"local_ip"`
	ConnectionType string                `json:"connection_type"`
	OS             string                `json:"os"`
	Browser        string                `json:"browser"`
	DeviceType     string                `json:"device_type"`
	TrafficSource  WebhookTrafficSource  `json:"traffic_source"`
	RiskScore      int                   `json:"risk_score"`
	Signals        []WebhookSignal       `json:"signals"`
	DetectionFlags WebhookDetectionFlags `json:"detection_flags"`
	ObservedAt     time.Time             `json:"observed_at"`
}

WebhookScoredData is the payload inside identification.scored.

type WebhookSignal

type WebhookSignal struct {
	Name   string `json:"name"`
	Weight int    `json:"weight"`
}

WebhookSignal is one scored signal.

type WebhookTrafficSource

type WebhookTrafficSource struct {
	Channel        string `json:"channel"`
	ReferrerDomain string `json:"referrer_domain"`
	LandingURL     string `json:"landing_url"`
	ClickIDType    string `json:"click_id_type"`
	UTMSource      string `json:"utm_source"`
	UTMMedium      string `json:"utm_medium"`
	UTMCampaign    string `json:"utm_campaign"`
	UTMContent     string `json:"utm_content"`
	UTMTerm        string `json:"utm_term"`
}

WebhookTrafficSource is traffic attribution.