PinBridge

Webhooks

Webhooks Overview

Use webhooks for push-based updates on publish lifecycle events.

Overview

Webhooks remove the need for heavy polling by pushing pin lifecycle updates to your endpoint.

What You Will Learn

  • When webhooks are preferable to polling.
  • How to register endpoints per workspace environment.
  • Operational requirements for reliable webhook consumers.

Implementation Checklist

  • Create at least one HTTPS webhook endpoint for production.
  • Persist event IDs to enforce idempotent processing.
  • Return 2xx quickly and offload heavy work to a queue.

Relevant Endpoints

POST
/v1/webhooks

Register a webhook endpoint and subscribed events.

GET
/v1/webhooks

List active webhook subscriptions.

GET
/v1/webhooks/{webhook_id}

Fetch one webhook subscription.

PATCH
/v1/webhooks/{webhook_id}

Update URL, secret, events, or enabled status.

DELETE
/v1/webhooks/{webhook_id}

Delete a webhook subscription.

Example

curl -X POST "$API_BASE_URL/v1/webhooks" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/webhooks/pinbridge",
    "secret": "replace-with-strong-secret",
    "events": ["pin.published", "pin.failed"],
    "is_enabled": true
  }'

Related Guides

Signature VerificationRetry Logic