GitHub Audit: Logs and Webhooks

"If you didn't log it, it didn't happen. In Enterprise security, visibility is the only shield."

In a large company with $500$ developers, you need to know Who did What and When.

• Who deleted the 'Main' branch?
• Who invited a stranger to the organization?
• Who changed the 'Production' secrets?

GitHub provides two tools for this: Audit Logs (History) and Webhooks (Real-time). This 1,500+ word guide is your architectural manual for high-level Organization Security and compliance.

---

1. Audit Logs: The "Black Box" of GitHub

Everything that happens in your organization is saved in the Audit Log for 180 days.

• The Search: You can filter by actor (the person) or action (the event).
• The Use Case: Use this to find out which developer has stopped using 2FA (Two-Factor Authentication). In 2026, 2FA is mandatory for any professional repo.

---

2. Webhooks: The "Nervous System"

A Webhook is a "POST" request that GitHub sends TO your server whenever something happens.

• Event: push: Tell your Slack bot to announce the new code.
• Event: repository.deleted: Send an EMERGENCY alert to the CTO.
• Event: member.added: Automatically set up their Google Cloud and Jira accounts.

---

3. Security: Webhook Secret Verification

If your server receives a "Message" saying "I am GitHub and someone just deleted the website," how do you know it's real? A hacker could be lying to you.

• The Solution: HMAC-SHA256.
• You set a "Secret" in GitHub.
• GitHub calculates a "Signature" using that secret and the message content.
• Your server calculates its own signature. If they don't match, you Ignore the message. This is the #1 rule of Webhook safety.

---

4. Log Streaming: Compliance (SOC2 / ISO)

If you are a bank or a healthcare company, you cannot wait for the 180-day limit.

• You must Stream your Audit Logs to a dedicated tool like Splunk, Datadog, or Azure Sentinel.
• This ensures that even if GitHub is hacked or goes down, you have a perfect, unchangeable record of every developer action.

---

5. Webhook "Replay": Debugging the Silence

What if your server was "Offline" when GitHub tried to send a webhook?

• GitHub has a "Recent Deliveries" tab.
• It shows the "Response Code" from your server (e.g., 500 Error).
• You can click "Redeliver" to try again. Pro-Tip: Use a "Message Queue" (like RabbitMQ or Redis) to handle webhooks so your server doesn't crash during a "Busy" hour with 10,000 pushes.

---

Summary: The Audit Checklist

1. Weekly Review: Check the Audit Log for any unexpected "Member Invitations."
2. Secret Secrets: Always verify Webhook signatures to prevent "Spoofing" attacks.
3. Steam Logs: Always stream logs to an external safe for compliance.
4. Queue Webhooks: Never process complex logic inside the Webhook receiver; put the task in a queue and return 200 OK instantly.
5. Role Access: Only 2 or 3 people in the company should have the power to view Audit Logs.

Audit Logs and Webhooks are the "Eyes and Ears" of your organization. By mastering the real-time response of webhooks and the historical integrity of logs, you gain the ability to manage massive, high-security teams with total confidence. You graduate from "Managing a repo" to "Architecting a Secure Organization."

Frequently Asked Questions

Q: What does the GitHub audit log record and who can access it? The audit log records security-relevant events across an organisation: member additions and removals, repository creation and deletion, permission changes, secret access, OAuth app authorisations, billing changes, and Actions workflow runs. Organisation owners and security managers can access it via the organisation's Settings → Audit log. The log is searchable and filterable, and can be streamed to a SIEM like Splunk or Datadog via audit log streaming for real-time monitoring.

Q: How do GitHub webhooks work and what are they used for? A webhook is an HTTP POST that GitHub sends to a URL you configure whenever a specified event occurs — push, pull request, release, issue comment, etc. Your server receives the payload, verifies the X-Hub-Signature-256 header (HMAC-SHA256 of the payload using your secret), and processes the event. Webhooks power CI/CD integrations, Slack notifications, deployment triggers, and any automation that needs to react to GitHub events in real time.

Q: How do you secure a GitHub webhook endpoint? Always validate the X-Hub-Signature-256 header on every incoming request — reject requests that fail the HMAC check. Use a long random secret (32+ characters) configured in both GitHub and your server. Serve the endpoint over HTTPS only. Consider IP allowlisting GitHub's webhook IP ranges (published at api.github.com/meta). Respond with HTTP 200 quickly and process the payload asynchronously to avoid GitHub's 10-second delivery timeout causing retries.

---

Part of the GitHub Mastery Course — engineering the oversight.