Skip to content

Webhook Setup Documentation

This document describes how to configure webhooks for real-time data synchronization in Dev Health Ops.

GitHub Configuration

  1. Go to your repository or organization Settings.
  2. Select Webhooks from the sidebar.
  3. Click Add webhook.
  4. Set Payload URL to https://your-dev-health-instance.com/api/v1/webhooks/github.
  5. Set Content type to application/json.
  6. Enter a Secret (must match GITHUB_WEBHOOK_SECRET environment variable).
  7. Select Let me select individual events:
  8. Pushes
  9. Pull requests
  10. Issues
  11. Deployments
  12. Workflow runs
  13. Click Add webhook.

GitLab Configuration

  1. Go to your project or group Settings > Webhooks.
  2. Set URL to https://your-dev-health-instance.com/api/v1/webhooks/gitlab.
  3. Set Secret token (must match GITLAB_WEBHOOK_TOKEN environment variable).
  4. Under Trigger, select:
  5. Push events
  6. Tag push events
  7. Merge request events
  8. Issue events
  9. Pipeline events
  10. Job events
  11. Click Add webhook.

Jira Configuration

  1. Log in as a Jira Administrator.
  2. Go to System > Webhooks.
  3. Click Create a Webhook.
  4. Set URL to https://your-dev-health-instance.com/api/v1/webhooks/jira.
  5. (Optional) Add ?secret=your_secret to the URL if JIRA_WEBHOOK_SECRET is configured.
  6. Under Events, select:
  7. Issue: created, updated, deleted.
  8. Click Create.

Environment Variables

Ensure the following variables are set in your deployment environment:

Variable Description
GITHUB_WEBHOOK_SECRET HMAC secret for GitHub signature validation
GITLAB_WEBHOOK_TOKEN Token for GitLab X-Gitlab-Token validation
JIRA_WEBHOOK_SECRET Optional secret for Jira validation
STRIPE_WEBHOOK_SECRET Stripe webhook signing secret (SaaS billing)
REDIS_URL Required for webhook delivery idempotency

Stripe Configuration (SaaS Billing)

Stripe webhooks are used for real-time subscription management in SaaS deployments. When a customer subscribes, upgrades, downgrades, or cancels, Stripe sends events directly to dev-health-ops.

  1. Go to your Stripe Dashboard > Developers > Webhooks.
  2. Click Add endpoint.
  3. Set Endpoint URL to https://your-dev-health-instance.com/api/v1/billing/webhooks/stripe.
  4. Under Events to send, select:
  5. checkout.session.completed
  6. customer.subscription.created
  7. customer.subscription.updated
  8. customer.subscription.deleted
  9. invoice.created
  10. invoice.updated
  11. invoice.finalized
  12. invoice.paid
  13. invoice.payment_failed
  14. invoice.voided
  15. charge.refunded
  16. charge.refund.updated
  17. Click Add endpoint.
  18. Copy the Signing secret and set it as STRIPE_WEBHOOK_SECRET in your environment.

Billing Endpoints

Endpoint Method Description
/api/v1/billing/webhooks/stripe POST Receives Stripe webhook events
/api/v1/billing/checkout POST Creates a Stripe Checkout Session (auth required)
/api/v1/billing/portal POST Creates a Stripe Customer Portal session (auth required)
/api/v1/billing/entitlements/{org_id} GET Returns current tier, features, and limits for an org

Required Environment Variables (Billing)

Variable Description
STRIPE_SECRET_KEY Stripe API secret key
STRIPE_WEBHOOK_SECRET Webhook signing secret from step 6 above
STRIPE_PRICE_ID_TEAM Stripe Price ID for the Team tier product
STRIPE_PRICE_ID_ENTERPRISE Stripe Price ID for the Enterprise tier product
LICENSE_PRIVATE_KEY Ed25519 private key for signing JWT licenses (base64-encoded)

Note: Stripe webhooks are only relevant for SaaS deployments. Self-hosted deployments use offline Ed25519 license keys and do not require Stripe configuration.

Email Notifications

When billing events are processed, the webhook handler sends email notifications to the organization owner:

Stripe Event Email Sent Recipient
invoice.paid Invoice receipt Org owner
invoice.payment_failed Payment failed alert Org owner
customer.subscription.updated Subscription changed (only if tier changed) Org owner
customer.subscription.deleted Subscription cancelled Org owner

Email delivery failures are logged but never prevent the webhook from returning a successful response. See Email Setup for provider configuration and troubleshooting.

For full local/CI/ops guidance (Stripe CLI forwarding, replay/retry, reconciliation, and test cards), see the Stripe Billing Runbook.