Webhooks: GitHub integration & outbound events
VipraGo supports an inbound GitHub webhook (HMAC-SHA256 verified) that links commits and pull requests to tasks, plus outbound event delivery to Slack, Microsoft Teams, and generic REST endpoints via automation rules.
Inbound: GitHub → VipraGo
- Endpoint: POST /webhooks/github?org_id=<your-organization-id> — public by design, secured by signature, never by JWT.
- In your GitHub repo: Settings → Webhooks → add the endpoint, content type application/json, and the shared secret from VipraGo's integration settings.
- Select events: push and pull_request are processed; others are acknowledged and ignored.
- VipraGo verifies the X-Hub-Signature-256 header (HMAC-SHA256 of the raw body with your shared secret); requests with missing or invalid signatures receive 401 and are never processed.
- On verified events, VipraGo extracts task keys (e.g., VPR-123) from branch names, commit messages, and PR titles, then attaches the commit/PR to those tasks — merged PRs can advance task status per your automation rules.
What gets linked
- Push events: commit message, commit URL, and ref are attached to every referenced task.
- Pull-request events: PR title, URL, and merge state; “Fixes VPR-123” in a merged PR can trigger a status transition.
- Event history is queryable per task, so reviewers see the engineering trail next to the work item.
Outbound: VipraGo → your tools
- Slack and Microsoft Teams: paste an incoming-webhook URL into Integrations; VipraGo posts formatted JSON cards for events you enable (task created/moved, leave approved, payroll published).
- Generic REST webhooks: automation rules (“when X then Y”) can POST JSON to any HTTPS endpoint you control.
- A connection test button sends a sample payload so you can verify wiring before enabling events.
Securing outbound endpoints
- Outbound deliveries to Slack/Teams use those platforms' own webhook-URL security model (the URL is the secret — treat it like a password).
- For generic endpoints: use a dedicated HTTPS URL with an unguessable path or token parameter, validate the expected JSON shape, respond 2xx quickly, and process asynchronously.
- Payload signing for generic outbound webhooks is on the roadmap; until then, prefer token-in-URL plus IP allowlisting.
Tips
- Rotate the GitHub shared secret periodically — update it in both GitHub and VipraGo in the same change window.
- Test signature failure deliberately once (wrong secret) to confirm your monitoring catches 401s.
FAQ
- Why is the GitHub endpoint public?
- GitHub's servers can't hold a VipraGo user session. Security comes from cryptographic signature verification: every request must carry a valid HMAC-SHA256 of the exact raw body, computed with a secret only GitHub and VipraGo know.
- Are outbound webhook payloads signed?
- Slack/Teams deliveries rely on their secret-URL model. Generic automation webhooks are not yet HMAC-signed — signing is on the roadmap; use unguessable endpoint tokens meanwhile.
- Which task keys are recognised?
- Your project keys (e.g., VPR-123) found in branch names, commit messages, and PR titles — multiple keys in one commit link to every referenced task.