Setting Up Webhooks

Webhooks enable automatic syncing whenever you push changes to GitHub, keeping your Notion pages up-to-date without manual intervention.

How Webhooks Work

1. You push changes to your GitHub repository
2. GitHub sends a webhook event to mdsync.app
3. mdsync.app verifies the webhook signature for security
4. The sync is automatically triggered for affected synchronizations
5. Your Notion pages are updated automatically

Plan Availability

• Free Plan: ❌ Webhooks not available (manual sync only)
• Starter Plan: ✅ Automatic webhooks included
• Pro Plan: ✅ Automatic webhooks included

Automatic Setup

When you create a synchronization and enable webhooks, mdsync.app automatically:

1. Creates a webhook in your GitHub repository
2. Configures it to trigger on push events
3. Generates and stores a webhook secret for security
4. Sets the webhook URL to point to mdsync.app's webhook endpoint
5. Verifies the webhook is working correctly

Webhook Security

• Signature Verification: All webhooks are verified using HMAC SHA-256 signatures
• Secret Management: Webhook secrets are encrypted and stored securely
• URL Validation: Webhook URLs are automatically updated if your app URL changes

Manual Setup (if needed)

If automatic setup fails, you can manually create the webhook:

1. Go to your GitHub repository → Settings → Webhooks
2. Click "Add webhook"
3. Payload URL: Use the webhook URL from your sync settings (format: https://mdsync.app/api/webhooks/github)
4. Content type: Select "application/json"
5. Events: Select "Just the push event"
6. Secret: Use the webhook secret from your sync settings
7. Click "Add webhook"

Managing Webhooks

• View Status: Check webhook status in your sync settings
• Update URL: Webhooks are automatically updated when needed
• Regenerate Secret: Contact support if you need to regenerate a webhook secret
• Delete: Webhooks are automatically deleted when you delete a synchronization

Troubleshooting

If webhooks aren't working:

• ✅ Check webhook delivery status in GitHub (Settings → Webhooks → Recent Deliveries)
• ✅ Verify the webhook URL is correct and accessible
• ✅ Ensure the webhook secret matches in both GitHub and mdsync.app
• ✅ Check your mdsync.app dashboard for sync errors
• ✅ Verify you're on a Starter or Pro plan
• ✅ Ensure you have admin access to the repository

Webhook Events

Currently, mdsync.app listens for:

• Push events: Triggers sync when code is pushed to the repository

• Pull request events
• Branch creation/deletion
• Custom webhook events