ShotGrid CI/CD Integration: Webhooks vs. API Polling Decision Guide

The Decision and Constraints

When a new Version is published in ShotGrid, downstream CI/CD pipelines often need to start a build immediately. The engineering decision is not whether to automate the trigger, but which mechanism to use: ShotGrid's native webhook system or a custom API polling service. The constraints that drive this choice are sub-5-second latency, guaranteed delivery without silent gaps, and minimal maintenance overhead.

Comparing Supported Options

Consideration	Native Webhook	API Polling
Latency	Near real-time; POST fires on event	Equal to poll interval (e.g., 30 s)
Delivery model	ShotGrid retries and orders events	Your service must detect and order records
Network posture	Requires publicly reachable HTTPS endpoint	Outbound-only; works behind strict firewalls
Maintenance	Handle duplicate posts and signature validation	Track last-poll state and manage API quota
Rate limits	Not subject to per-user API request limits	Consumes API quota (default 100 req/min per user)

Trade-offs in Practice

Native webhooks push a JSON payload to a URL you control when an event such as Version Published occurs. ShotGrid manages retries, event ordering, and security signatures, which reduces the code you must maintain. The cost is operational: your endpoint must be reachable from ShotGrid's cloud IPs, and you must tolerate duplicate deliveries by making your build trigger idempotent.

API polling queries the ShotGrid REST API on a fixed schedule—for example, GET /api/v1/entity/Version with a filter on published_at—and processes new records. This approach works entirely from behind a firewall and gives you full control over timing and batching. However, latency is bounded by the interval you choose, and every request counts against ShotGrid's API rate limits. Without careful backoff, a busy site can trigger HTTP 429 responses.

Implementing the Webhook Path

If your infrastructure can expose a public HTTPS endpoint, the webhook path is usually the lower-maintenance choice for sub-5-second latency.

Endpoint Logic

Your receiver must validate the ShotGrid signature, extract the Version ID, call your CI system, and acknowledge receipt. The following illustrative pattern shows the core logic; adapt it to your language and framework.

# Illustrative webhook receiver (run on your CI/CD host or relay)
import hmac, hashlib, json
from flask import Flask, request, abort

app = Flask(__name__)
# Secret generated when you create the webhook in ShotGrid
WEBHOOK_SECRET = b"<webhook-secret-from-shotgrid>"

@app.route("/shotgrid/version-published", methods=["POST"])
def version_published():
    # 1. Verify authenticity using HMAC-SHA256
    provided_sig = request.headers.get("<signature-header-name>")
    computed_sig = hmac.new(
        WEBHOOK_SECRET, request.get_data(), hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(provided_sig, computed_sig):
        abort(401)

    # 2. Extract Version ID and trigger CI build
    event = request.get_json()
    version_id = event["data"]["id"]
    # trigger_ci_build(version_id)

    # 3. Acknowledge so ShotGrid stops retrying
    return "", 200

ShotGrid Configuration

1. In ShotGrid, navigate to Admin → Webhooks → New Webhook.
2. Select the Version Published event.
3. Set the URL to your public HTTPS endpoint.
4. Save and copy the generated secret into your endpoint configuration.

Implementing the Polling Path

If a public endpoint is not feasible, run a scheduled job from your automation host. The job stores the timestamp of the last successful poll and queries for Versions published since then.

# Conceptual polling query (run from your scheduler or automation host)
# Replace placeholders with your site URL, API credentials, and last-poll timestamp
curl -X GET \
  "https://<your-site>.shotgunstudio.com/api/v1/entity/Version?filters=[[%22published_at%22,%22greater_than%22,%22<last-poll-timestamp>%22]]" \
  -H "Authorization: Bearer <api-access-token>"

After each successful query, persist the newest published_at value as the next <last-poll-timestamp>. Wrap the call in exponential backoff so that HTTP 429 responses do not cascade into throttling.

Verifying the Integration

• Webhook: Use the Test Webhook button in ShotGrid's admin UI. Confirm your endpoint receives a POST containing the expected signature header and a test Version ID.
• Polling: Run the script against a sandbox ShotGrid site, publish a Version, and verify the script detects the record within the configured interval.
• Both paths: Inspect logs for duplicate processing. Use the Version ID as an idempotency key so the same event never triggers two builds.

Limitations and Operational Checks

Webhook delivery depends on network reachability. If ShotGrid's cloud IPs cannot reach your endpoint because of firewall rules or private networking, delivery will fail unless you deploy a relay or VPN. Polling scripts must respect ShotGrid's default API rate limit of 100 requests per minute per user; exceeding it risks throttling. In both designs, treat the Version ID as the deduplication key and audit your build logs to confirm that exactly one build runs per published Version.