Webhook API Reference

This API allows your service to send webhook events to Gigit.

Authentication

All API requests require authentication using the x-webhook-auth header:

x-webhook-auth: your_webhook_auth_token

Please reach out to your Gigit representative to get your webhook auth token.

Webhook Endpoint

POST /api/v1/webhooks/profiles

Send webhook events to Gigit.

Request Body

{
  "event_type": "event_type",
  "source": {
    "shop_url": "your-store.myshopify.com",
    "platform": "test-integration-app"
  },
  "profile": {
    "email": "customer@example.com",
    "gigit_id": "ggt_1234567890"
  },
  "request_id": "24376536-4311-41e1-b143-896a4661fdec" 
}

Field	Type	Required	Description
event_type	string	Yes	The type of event being reported
source.shop_url	string	Yes	URL of the shop triggering the event
source.platform	string	Yes	Platform identifier (e.g., "shopify")
profile.email	string	Yes	Valid customer email address
profile.gigit_id	string	Yes	Gigit identifier for the customer
request_id	string	No	UUID for tracking the request

Response

A successful request returns HTTP 200 with this response body:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "success": true,
  "status_code": 200,
  "message": "Email and gigit_id association successfully recorded",
  "request_id": "24376536-4311-41e1-b143-896a4661fdec", 
  "timestamp": "2025-04-29T12:34:56.789Z"
}

Field	Type	Description
id	string	Gigit-generated UUID for the processed webhook request
success	boolean	Indicates successful processing
status_code	integer	HTTP status code (200 for success)
message	string	Human-readable success message
request_id	string	Your original request ID (if provided)
timestamp	string	ISO 8601 formatted timestamp of the response

Error Responses

All errors return a consistent format:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "error_code",
  "status_code": 400,
  "message": "Human-readable error explanation",
  "request_id": "24376536-4311-41e1-b143-896a4661fdec",
  "timestamp": "2025-04-29T12:34:56.789Z"
}

Field	Type	Description
id	string	UUID for tracking the error
error	string	Error code identifier
status_code	integer	HTTP status code
message	string	Human-readable error explanation
request_id	string	Your original request ID (if provided)
timestamp	string	ISO 8601 formatted timestamp of the response

Error Types

Status Code	Error Code	Description
400	invalid_request	Missing required fields or invalid data format
401	unauthorized	Missing webhook authentication token
403	unauthorized_shop	Shop not authorized or doesn't exist
500	internal_server_error	Unexpected server-side error

Examples

Example Request

curl -X POST {host}/api/v1/webhooks/profiles \
  -H "Content-Type: application/json" \
  -H "x-webhook-auth: your_webhook_auth_token" \
  -d '{
    "event_type": "customer_identified",
    "source": {
      "shop_url": "your-store.myshopify.com",
      "platform": "shopify"
    },
    "profile": {
      "email": "customer@example.com",
      "gigit_id": "ggt_1234567890"
    },
    "request_id": "24376536-4311-41e1-b143-896a4661fdec"
  }'

Example Success Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "success": true,
  "status_code": 200,
  "message": "Email and gigit_id association successfully recorded",
  "request_id": "24376536-4311-41e1-b143-896a4661fdec",
  "timestamp": "2025-04-29T12:34:56.789Z"
}

Example Error Response (Missing Field)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "invalid_request",
  "status_code": 400,
  "message": "Missing required fields in the request body.",
  "request_id": "24376536-4311-41e1-b143-896a4661fdec",
  "timestamp": "2025-04-29T12:34:56.789Z"
}

License

This is a private library. Unauthorized distribution or modification is prohibited.

Support

For issues or feature requests, please email us at info@gigit.ai.