GitHub Webhooks

Set up GitHub webhooks to automatically deploy when you push to your repository.

How It Works

GitHub                     Expose Server              Container
   │                            │                         │
   ├── Push to main ───────────►│                         │
   │                            ├── Verify signature      │
   │                            ├── Clone repo            │
   │                            ├── Build image           │
   │                            ├── Push to registry      │
   │                            ├── Start container ─────►│
   │                            │                         │

Setting Up Webhooks

1. Get Webhook URL

Your webhook URL is:

https://api.yourdomain.com/api/v1/webhooks/github/{deployment_id}

Find the deployment ID in the deployment detail view.

2. Configure GitHub

1. Go to your repository on GitHub
2. Click Settings → Webhooks
3. Click Add webhook
4. Configure:

Field	Value
Payload URL	https://api.yourdomain.com/api/v1/webhooks/github/{deployment_id}
Content type	application/json
Secret	Your webhook secret (from server .env)
Events	Just the push event

5. Click Add webhook

3. Test the Webhook

1. Push a commit to your repo
2. Check GitHub webhook deliveries
3. Verify deployment triggered in Expose

Webhook Security

Signature Verification

Expose verifies the X-Hub-Signature-256 header using HMAC-SHA256:

HMAC-SHA256(webhook_secret, request_body) == signature

This ensures webhooks are actually from GitHub.

Configure Secret

In your server’s .env:

WEBHOOK_SECRET=your-secure-random-secret

Generate with:

openssl rand -hex 32

Use the same secret in GitHub webhook configuration.

Branch Filtering

By default, webhooks trigger on pushes to any branch. Expose filters:

• Only deploys if pushed branch matches deployment’s configured branch
• Other branches are ignored

Example:

• Deployment configured for main branch
• Push to feature-x → No deploy
• Push to main → Deploy triggered

Webhook Events

Supported Events

Event	Action
push	Triggers deploy if branch matches

Event Payload

Expose extracts from the payload:

• ref: Branch reference (e.g., refs/heads/main)
• after: Commit SHA

Troubleshooting

Webhook Not Triggering

1. Check GitHub webhook deliveries for errors
2. Verify webhook URL is correct
3. Check server logs: docker logs expose-server | grep webhook

Signature Verification Failed

• Ensure secrets match in GitHub and server .env
• No extra whitespace in secret
• Webhook content type is application/json

Deploy Not Starting

• Verify branch matches deployment configuration
• Check deployment exists and is active
• Look for errors in server logs

Multiple Deployments

For the same repo with different branches:

1. Create separate deployments
2. Configure each with different branch
3. Set up separate webhooks (or one webhook handles all)

Example:

Deployment: api-prod   Branch: main     → api.hosted.domain.com
Deployment: api-staging Branch: develop → api-staging.hosted.domain.com

CI/CD Integration

Webhooks work alongside CI/CD:

Push → GitHub Actions → Tests Pass → Webhook → Deploy

Configure GitHub to only trigger webhook after CI passes using branch protection rules.

Disabling Webhooks

To stop auto-deploys:

1. Go to GitHub → Settings → Webhooks
2. Find the webhook
3. Click Delete

Or disable temporarily by unchecking Active.