Instant Asset Change Alerts with Shotgrid Webhooks

Why the Old Polling Model Still Hurts

Production pipelines often rely on polling Shotgrid for changes. Every few minutes you hit the API, parse the response, and decide if anything new happened. This introduces latency, unnecessary API calls, and a heavier load on both your servers and Shotgrid’s endpoints. When an asset’s status flips from In Review to Approved, you might not react until the next poll cycle.

Enter Shotgrid Webhooks

Shotgrid’s Webhook system delivers a POST request to a URL you specify as soon as a subscribed event occurs. No polling, no delay.

What a Webhook Is

A webhook is a lightweight HTTP callback. When a pre‑defined event happens in Shotgrid, it serialises a JSON payload and posts it to your endpoint. Your server can then act on the data immediately.

Supported Events

• asset.status_changed – triggered when an asset’s status field updates.
• task.completed – fired when a task’s status becomes Completed.
• Custom events can be added via the settings > webhooks UI.

Step‑by‑Step: Create a Webhook for Asset Status Changes

1. Navigate to Settings

   In the Shotgrid UI, go to Settings > Webhooks. Only available in Shotgrid Enterprise.

2. Create New Webhook

   Click New Webhook and fill in:

   • Name: Asset Status Notifier
   • Endpoint URL: https://example.com/shotgrid/notify
   • Events: Check asset.status_changed
   • Secret Key: (optional) a random string to sign the payload for verification.
3. Save and note the Webhook ID that appears.
4. Test the Webhook

   Shotgrid provides a Test button that sends a sample payload to your URL. Use a tool like ngrok or a local HTTP server to capture it.

Handling the Payload in Your Endpoint

Below is a minimal Python Flask example that verifies the signature (if you set a secret key) and prints the event data.

from flask import Flask, request, abort
import hmac, hashlib

app = Flask(__name__)
SECRET = "YOUR_SECRET_KEY"  # Replace with the key you set in Shotgrid

@app.route("/shotgrid/notify", methods=['POST'])
def shotgrid_notify():
    # Verify signature if secret is set
    if SECRET:
        signature = request.headers.get("X-Shotgrid-Signature", "")
        body = request.get_data()
        expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
        if not hmac.compare_digest(signature, expected):
            abort(400, "Invalid signature")
    payload = request.json
    # Example: react to status change
    if payload.get("event_type") == "asset.status_changed":
        asset_id = payload["data"]["id"]
        new_status = payload["data"]["fields"]["status"]
        print(f"Asset {asset_id} status changed to {new_status}")
        # Trigger downstream job here
    return "OK", 200

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

Make sure your server is reachable from the internet, or use a tunnelling tool during development.

Security Considerations

• Secret Signing – Shotgrid can sign the payload with HMAC SHA‑256. Verify the X-Shotgrid-Signature header to ensure the request is authentic.
• HTTPS Only – Shotgrid will only POST to HTTPS endpoints. Self‑signed certs work locally but should be replaced with a trusted CA in production.
• Rate Limits – Shotgrid enforces a per‑webhook rate limit (default 10 requests/second). If your pipeline is bursty, consider a queue to buffer events.

Trade‑Offs and Limitations

While webhooks eliminate polling, they bring their own challenges:

• Reliability – If your endpoint is down or the network fails, Shotgrid will retry up to 3 times with exponential back‑off. Events can still be missed; a fallback polling routine is wise.
• Payload Changes – Shotgrid may alter the JSON schema between releases. Validate the structure before processing or keep a changelog of your own.
• Edition Restriction – Webhooks are only available in Shotgrid Enterprise. Free or community editions must rely on polling.
• Security Overhead – You must maintain HTTPS, handle certificate renewal, and guard against replay attacks if you use signing.

Practical Checklist Before Going Live

1. Confirm your production server can accept HTTPS POSTs from Shotgrid’s IP ranges.
2. Set a secret key and implement signature verification.
3. Test the webhook with the Shotgrid Test button and capture the payload with ngrok or a local listener.
4. Implement idempotent handling – if the same event arrives twice, it should not double‑process.
5. Set up monitoring: log each received event and alert on failures.
6. Optional: add a simple polling fallback that runs every 10 minutes to catch missed events.

Once these steps are in place, your pipeline will react to asset status changes in near real‑time, freeing resources and reducing latency.

Takeaway

Shotgrid Webhooks turn the classic polling problem into a push‑based, low‑latency solution. By configuring a single webhook, verifying signatures, and handling the JSON payload, you can trigger downstream processes instantly. Remember to secure your endpoint, monitor for missed events, and keep a lightweight fallback in case of network hiccups.