Webhook Payload

When garment tagging completes and webhooks are enabled, Aistetic sends an HTTP POST request to your configured webhook URL with the tagging results. This page documents the payload format, headers, signature verification, and retry policy.

HTTP Headers

Each webhook delivery includes the following headers:

Header	Description
Content-Type	application/json
X-Webhook-Event	The event type (e.g., tagging.completed)
X-Delivery-ID	A unique identifier for this delivery attempt
X-Webhook-Signature	HMAC-SHA256 signature (only if secret is configured). Format: sha256={hex_signature}

Any custom headers configured via Update Config are also included.

Events

Event	Description
tagging.completed	Garment tagging has finished processing. Includes full tagging results.
webhook.test	Test event sent via the Test endpoint.

Payload Format

tagging.completed

{
  "event": "tagging.completed",
  "timestamp": "2025-02-03T16:35:00Z",
  "uuid": "12345",
  "status": "complete",
  "annotated_img": "https://storage.example.com/annotated/12345.jpg",
  "tag": {
    "garment_type": "Dress",
    "color": "Blue",
    "pattern": "Solid",
    "sleeve_length": "Long Sleeve",
    "neckline": "V-Neck",
    "fit": "Regular"
  },
  "reflection_tag": {
    "garment_type": "Dress",
    "color": "Blue"
  },
  "measurements": {
    "length": 100,
    "bust": 90,
    "waist": 70
  },
  "description": "A blue V-neck dress with long sleeves in a regular fit."
}

The tag, measurements, and description fields match the format returned by the Query endpoint.

webhook.test

{
  "event": "webhook.test",
  "timestamp": "2025-02-03T16:30:00Z",
  "message": "This is a test webhook from Aistetic",
  "domain": "your-domain"
}

Signature Verification

If you have configured a secret in your webhook settings, each delivery includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body. Use this to verify that the webhook was sent by Aistetic and has not been tampered with.

Verification Steps

1. Extract the signature from the X-Webhook-Signature header
2. Compute HMAC-SHA256 of the raw request body using your secret
3. Compare the computed signature with the received one using a constant-time comparison

Example (Python)

import hmac
import hashlib

def verify_webhook_signature(payload_bytes, secret, received_signature):
    """
    Verify the webhook signature.

    Args:
        payload_bytes: Raw request body bytes
        secret: Your webhook secret string
        received_signature: Value of the X-Webhook-Signature header

    Returns:
        True if signature is valid
    """
    expected = "sha256=" + hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, received_signature)

Example (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payloadBuffer, secret, receivedSignature) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payloadBuffer)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSignature)
  );
}

Retry Policy

If your webhook endpoint is unreachable or returns a non-2xx HTTP status code, Aistetic will retry delivery with exponential backoff:

Attempt	Delay After Failure
1	10 seconds
2	1 minute
3	10 minutes
4	1 hour
5	2 hours
6	4 hours
7	8 hours
8	24 hours
9	48 hours

After 9 failed attempts, the delivery is marked as permanently_failed. You can check delivery status using the Delivery Status endpoint.

Responding to Webhooks

Your endpoint should return a 2xx HTTP status code to acknowledge receipt. The response body is ignored.

If your endpoint does not respond within a reasonable timeout or returns a non-2xx status code, the delivery will be retried according to the retry policy above.