Designing Robust Shotgrid Webhook Subscribers for Task Status Changes

Problem: Silent webhook failures when Shotgrid task status changes

Your team needs to react instantly whenever a task moves from In Progress to Done in Shotgrid. Out of the box, the event system publishes JSON payloads, but without proper signature verification and timeout handling, downstream services can silently drop events, retry loops, or fail security checks.

Smallest suitable design

Deploy a lightweight endpoint that:

• Accepts POST requests from Shotgrid
• Validates the X-Shotgrid-Signature header using your project's API secret
• Responds with HTTP 200 within the configured timeout (default 10 seconds)
• Idempotently processes the event using the payload's unique event ID

Trust and data boundaries

Each payload includes the entity ID, old value, new value, and event type. Shotgrid scopes events to the project where the webhook is registered. If your service subscribes across projects, you must perform explicit permission checks; the payload does not carry project context beyond the entity ID.

Operational checks

1. In Shotgrid, navigate to Admin > Tools > Webhooks and create a new webhook on the Task entity with the status trigger.
2. Set the endpoint URL to your HTTPS endpoint.
3. Send a test status change on any task.
4. Inspect the incoming request: the body should contain {entity_id: ..., old_value: "In Progress", new_value: "Done", event_type: "task.status_changed"}. The header X-Shotgrid-Signature will contain an HMAC-SHA256 hex digest.
5. Compute HMAC-SHA256(project_api_secret, raw_payload) and compare it to the header value. Match confirms the payload is authentic and untampered.

Failure modes and conditions that change the design

• Signature mismatch: indicates the payload was modified in transit or the wrong API secret is being used. Recheck the project's API secret and the encoding (raw body vs. JSON string).
• Timeout exceeded: if your endpoint takes longer than the configured timeout, Shotgrid retries with exponential backoff. Ensure your handler returns 200 quickly; defer heavy work to a background queue.
• Cross-project trigger without permission: the event fires but your service lacks the required API scope. Add the necessary permissions or scope the webhook to a single project.
• OAuth vs. API key: for server-to-server integrations, OAuth tokens are supported. Switch to OAuth if your organization enforces token rotation or least-privilege access.

Limitation: Shotgrid webhooks are project-scoped. A single webhook cannot listen for status changes across all projects without registering one per project, or implementing a central dispatcher that checks project membership before processing.