Skip to main content

​
Webhook Integration

Use webhooks to build real-time integrations — notify your CRM when staging completes, alert agents when images are ready, or trigger downstream workflows.

​
Setup

​
1. Create a webhook endpoint

# Flask example
from flask import Flask, request, jsonify
import hmac, hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_xxxxxxxxxxxxx"

@app.route("/webhooks/staging", methods=["POST"])
def handle_webhook():
    # Verify signature
    signature = request.headers.get("X-Webhook-Signature", "")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(f"sha256={expected}", signature):
        return jsonify({"error": "Invalid signature"}), 401

    event = request.json
    event_type = event["event"]

    if event_type == "staging.complete":
        image_url = event["data"]["image_url"]
        claim_code = event["data"]["claim_code"]
        # Send to your CRM, notify the agent, etc.
        print(f"Staging complete: {claim_code}")

    elif event_type == "claim.redeemed":
        print(f"Agent claimed: {event['data']['claim_code']}")

    elif event_type == "credits.low":
        print(f"Low credits: {event['data']['current_balance']}")

    return jsonify({"received": True}), 200

​
2. Register the webhook

curl -X PUT .../api/v1/keys/12/webhook \
  -H "Authorization: Bearer <firebase-token>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhooks/staging", "enabled": true}'

​
3. Test it

curl -X POST .../api/v1/keys/12/webhook/test \
  -H "Authorization: Bearer <firebase-token>"

​
Best practices

  • Always verify the X-Webhook-Signature header
  • Return 200 quickly — process events asynchronously if needed
  • Handle duplicate events idempotently (use event.timestamp as dedup key)
  • Set up monitoring for webhook failures