Webhooks

Docs

Webhooks

Set up POST endpoints to receive real-time notifications for sync events.

Webhooks allow you to receive real-time HTTP POST notifications when events occur in your Repo File Sync organization. Use them to integrate with external systems, trigger CI/CD pipelines, or build custom workflows.

Setting Up a Webhook

Navigate to Settings → Developers → Webhooks in your organization dashboard
Click "Add Endpoint"
Enter the URL of your POST endpoint
Save the webhook

Your endpoint will start receiving event notifications immediately.

Event Types

Webhooks are triggered for the following events:

Event	Description
`sync_task.completed`	A sync task finished executing successfully
`sync_task.failed`	A sync task encountered an error during execution
`pull_request.created`	A new pull request was created in a target repository
`pull_request.merged`	A sync pull request was merged
`drift.detected`	Drift was detected in a synced repository

Payload Format

All webhook payloads are sent as JSON with the following structure:

{
  "event": "sync_task.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization": {
    "id": "org_abc123",
    "name": "My Organization"
  },
  "data": {
    // Event-specific payload
  }
}

Security

To verify that a webhook request is genuinely from Repo File Sync:

HTTPS only: Always use HTTPS endpoints to ensure payloads are encrypted in transit
IP allowlisting: Restrict incoming requests to Repo File Sync's IP ranges if your infrastructure supports it

Best Practices

Respond quickly: Return a 2xx status code within a few seconds. Offload heavy processing to a background job
Handle duplicates: Design your endpoint to be idempotent — the same event may be delivered more than once
Monitor failures: Check the webhook delivery logs in your dashboard to catch endpoint errors early
Use HTTPS: Always use secure endpoints to protect webhook payloads

Troubleshooting

Not receiving events? Verify the endpoint URL is correct and publicly accessible
Getting 4xx/5xx errors? Check your server logs and ensure the endpoint accepts POST requests with a JSON body
Events delayed? Failed deliveries are retried with exponential backoff. Check your endpoint's uptime

For additional help, contact us.

API Keys