GitHub webhooks notify your endpoint of repository events like pushes or pull requests. They use optional signature verification for security, with no initial challenge. This pattern is common for services prioritizing payload integrity over setup ceremonies.

Quickstart

1) Register the Webhook in GitHub

Registration establishes the shared secret and URL. In GitHub:

1. Navigate to your repository > Settings > Webhooks > Add webhook.

2. Payload URL: Your Agent Studio listener URL (e.g., https://your-instance.moveworks.ai/webhooks/v1/listeners/your-listener/notify). This is where GitHub sends POST requests.

3. Content type: application/json.

4. Generate and enter a strong Secret,this becomes the key for HMAC signing, shared only between GitHub and your listener.

5. Select individual events (e.g., Push events) to control what triggers notifications.

   Event	Description	Key Payload Fields
   push	Code pushed to repository	commits, repository
   pull_request	Pull request actions	action, pull_request

6. Add webhook.

Upon saving, GitHub sends a “ping” event (identified by header x-github-event: ping). This tests connectivity but doesn’t require special handling, treat it as a valid event.

2) Configure Verification in Agent Studio

Signature verification ensures authenticity. GitHub signs the raw body with HMAC-SHA256, sending the result in a header. In Agent Studio’s Verification panel:

1. Open the Verification panel and add a new rule.
2. Select Validation Type: Signature Verification (HMAC).
3. Add a Signature Verification Rule
4. In Secret Shared by External System, paste the secret from GitHub. This is the symmetric key; mismatches cause verification failures.
5. Set Signature Verification Hash Mode to HMAC-SHA256, matching GitHub’s algorithm
6. For Verification Payloads, type raw_body. GitHub signs the unparsed bytes, so this preserves exact content
7. Verification Received Signature: headers["x-hub-signature-256"]. This header includes a sha256= prefix, which Agent Studio infers and strips during comparison

These fields interconnect: The payload feeds into HMAC with the secret and mode, producing an expected signature matched against the received one

Gotchas

• If no secret is set in GitHub, the signature header is absent; configure verification as optional if needed.

GitHub Documentation

• Validating webhook deliveries
• Creating webhooks