Webhooks and Events

Big Picture webhooks notify external systems when events occur. Webhooks enable automation, monitoring, and integration with notification and workflow systems.

How Webhooks Work

Webhooks send HTTP POST requests to configured endpoints when events occur:

Event occurs — Release created, approval decision made, policy changed, etc.
Webhook triggered — Big Picture sends HTTP POST to webhook URL
External system receives — External system processes webhook payload
Response expected — Big Picture expects HTTP 2xx response

Webhooks enable real-time integration without polling. External systems receive events immediately when they occur.

Supported Events

Big Picture supports webhooks for these event types:

Release Events

release.created — New release created
release.published — Release published to channel
release.approved — Release approved for distribution
release.rejected — Release rejected

Policy Events

policy.updated — Tenant policy updated
policy.created — Tenant policy created
policy.deleted — Tenant policy deleted

Approval Events

approval.requested — Approval requested for release
approval.approved — Approval granted
approval.rejected — Approval rejected
approval.expired — Approval request expired

License Events

license.issued — License lease issued
license.revoked — License lease revoked
license.expired — License lease expired

Artifact Events

artifact.registered — Artifact registered
artifact.verified — Artifact verification completed

Webhook Configuration

Create Webhook

Create webhook with event subscriptions:

curl -X POST "${BP_BASE_URL}/v1/webhooks" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/bigpicture",
    "events": [
      "release.created",
      "release.published",
      "approval.approved"
    ],
    "secret": "webhook-secret-key"
  }'

Webhook Payload

Webhook payloads include event type, timestamp, and event-specific data:

{
  "event": "release.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "release_id": "rel_abc123",
    "product_id": "prod_xyz789",
    "version": "1.0.0",
    "channel": "stable"
  }
}

Webhook Signature

Webhooks include HMAC-SHA256 signature for verification:

X-BigPicture-Signature: sha256=abc123...

Verify signatures using webhook secret:

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Webhook Endpoints

Endpoint Requirements

Webhook endpoints must:

Accept HTTP POST requests
Return HTTP 2xx status codes for success
Handle webhook payloads (JSON)
Verify webhook signatures
Process events idempotently

Endpoint Implementation

Example webhook endpoint:

from flask import Flask, request
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "webhook-secret-key"

@app.route('/webhooks/bigpicture', methods=['POST'])
def webhook():
    payload = request.get_data(as_text=True)
    signature = request.headers.get('X-BigPicture-Signature')

    # Verify signature
    if not verify_signature(payload, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401

    # Parse event
    event = request.json
    event_type = event['event']
    event_data = event['data']

    # Handle event
    if event_type == 'release.created':
        handle_release_created(event_data)
    elif event_type == 'approval.approved':
        handle_approval_approved(event_data)

    return 'OK', 200

Event Payloads

Release Created

{
  "event": "release.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "release_id": "rel_abc123",
    "product_id": "prod_xyz789",
    "version": "1.0.0",
    "channel": "stable",
    "artifacts": [
      {
        "artifact_id": "art_abc123",
        "platform": "windows",
        "arch": "x86_64"
      }
    ]
  }
}

Approval Approved

{
  "event": "approval.approved",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "approval_id": "appr_abc123",
    "release_id": "rel_abc123",
    "approved_by": "user_xyz789",
    "approved_at": "2024-01-15T10:35:00Z"
  }
}

Policy Updated

{
  "event": "policy.updated",
  "timestamp": "2024-01-15T10:40:00Z",
  "data": {
    "tenant_id": "tenant_abc123",
    "policy_id": "policy_xyz789",
    "update_action": "MANAGED_BY_IT",
    "updated_by": "user_xyz789"
  }
}

Webhook Management

List Webhooks

curl -X GET "${BP_BASE_URL}/v1/webhooks" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Get Webhook

curl -X GET "${BP_BASE_URL}/v1/webhooks/${WEBHOOK_ID}" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Update Webhook

curl -X PUT "${BP_BASE_URL}/v1/webhooks/${WEBHOOK_ID}" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "release.created",
      "release.published"
    ]
  }'

Delete Webhook

curl -X DELETE "${BP_BASE_URL}/v1/webhooks/${WEBHOOK_ID}" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Retry Logic

Big Picture retries failed webhook deliveries:

Initial attempt — Immediate delivery
Retry attempts — Exponential backoff (1s, 2s, 4s, 8s, 16s)
Max retries — 5 retry attempts
Timeout — 30 second timeout per attempt

Webhooks that fail after all retries are logged for manual review.

Best Practices

Verify signatures — Always verify webhook signatures
Idempotent processing — Process events idempotently (handle duplicates)
Fast responses — Return HTTP 2xx quickly, process asynchronously if needed
Error handling — Handle errors gracefully, log failures
Event filtering — Subscribe only to needed events
Secret management — Store webhook secrets securely

Troubleshooting

Webhooks not received — Verify webhook URL is accessible and returns 2xx

Signature verification fails — Check webhook secret matches configuration

Events not triggering — Verify event subscriptions include desired events

Retry failures — Check endpoint availability and response times

Reference: API Overview — API documentation for webhook endpoints
Workflows: Approving a Release — Approval workflow procedures