RepositoryWebhook

Manage GitHub repository webhooks with automatic lifecycle management.

Webhooks allow external services to be notified when certain events happen in a repository. This resource manages the full lifecycle of repository webhooks including creation, updates, and deletion.

Basic Usage

Create a simple webhook for push events:

import { RepositoryWebhook } from "alchemy/github";

const webhook = await RepositoryWebhook("my-webhook", {
  owner: "my-org",
  repository: "my-repo",
  url: "https://my-service.com/github-webhook",
  events: ["push"]
});

With Secret Validation

Add webhook secret for payload validation:

import { RepositoryWebhook } from "alchemy/github";
import { alchemy } from "alchemy";

const webhook = await RepositoryWebhook("secure-webhook", {
  owner: "my-org",
  repository: "my-repo",
  url: "https://ci.example.com/webhook",
  secret: alchemy.secret("GITHUB_WEBHOOK_SECRET"),
  events: ["push", "pull_request", "release"],
  contentType: "application/json"
});

Multiple Events

Listen to multiple GitHub events:

import { RepositoryWebhook } from "alchemy/github";

const ciWebhook = await RepositoryWebhook("ci-webhook", {
  owner: "my-org",
  repository: "my-repo",
  url: "https://ci.example.com/webhook",
  events: [
    "push",
    "pull_request",
    "release",
    "issues",
    "issue_comment"
  ]
});

All Events

Create a webhook that listens to all repository events:

import { RepositoryWebhook } from "alchemy/github";

const monitoringWebhook = await RepositoryWebhook("monitoring-webhook", {
  owner: "my-org", 
  repository: "my-repo",
  url: "https://monitoring.internal.com/github",
  events: ["*"], // Listen to all events
  insecureSsl: true, // For internal services with self-signed certs
  contentType: "application/x-www-form-urlencoded"
});

Custom SSL Configuration

For internal services or development environments:

import { RepositoryWebhook } from "alchemy/github";

const devWebhook = await RepositoryWebhook("dev-webhook", {
  owner: "my-org",
  repository: "my-repo", 
  url: "https://localhost:3000/webhook",
  insecureSsl: true, // Skip SSL verification
  active: false, // Create inactive webhook
  events: ["push", "pull_request"]
});

Properties

Property	Type	Required	Description
owner	string	✅	Repository owner (user or organization)
repository	string	✅	Repository name
url	string	✅	The URL to which the payloads will be delivered
secret	string		Webhook secret for payload validation
contentType	"application/json" | "application/x-www-form-urlencoded"		The media type used to serialize the payloads (default: "application/json")
insecureSsl	boolean		Determines whether the SSL certificate of the host for url will be verified (default: false)
active	boolean		Determines if notifications are sent when the webhook is triggered (default: true)
events	string[]		Determines what events the hook is triggered for (default: ["push"])
token	string		Optional GitHub API token (overrides environment variable)

Returns

Property	Type	Description
id	string	Resource identifier
webhookId	number	The numeric ID of the webhook in GitHub
url	string	The webhook URL that was configured
createdAt	string	Time at which the webhook was created
updatedAt	string	Time at which the webhook was last updated
pingUrl	string	The ping URL for testing the webhook
testUrl	string	The test URL for the webhook

GitHub Events

Common GitHub webhook events you can listen to:

• push - Any Git push to a Repository
• pull_request - Pull request activity
• issues - Issue activity
• issue_comment - Issue comment activity
• release - Release activity
• create - Branch or tag created
• delete - Branch or tag deleted
• fork - Repository forked
• star - Repository starred
• watch - Repository watched
• workflow_run - GitHub Actions workflow run
• * - All events

For a complete list of available events, see the GitHub Webhooks documentation.

Authentication

The resource requires a GitHub token with appropriate permissions:

export GITHUB_TOKEN="ghp_your_token_here"

The token must have:

• repo scope for private repositories
• public_repo scope for public repositories
• Admin access to the repository to manage webhooks

Error Handling

The resource handles common GitHub API errors:

• 403 Forbidden: Token lacks admin rights to the repository
• 422 Unprocessable Entity: Invalid webhook configuration (bad URL, invalid events, etc.)
• 404 Not Found: Repository doesn't exist or token lacks access

Updates

When updating a webhook, you can change:

• Webhook URL
• Events list
• Secret
• Content type
• SSL verification settings
• Active status

The webhook ID remains the same during updates.

Security

• Always use HTTPS URLs for webhook endpoints
• Use webhook secrets to validate payload authenticity
• Consider using insecureSsl: false (default) for production
• Regularly rotate webhook secrets

Best Practices

1. Use secrets: Always configure webhook secrets for payload validation
2. Specific events: Only listen to events your application needs
3. Error handling: Implement proper error handling in your webhook receiver
4. Testing: Use the pingUrl to test webhook connectivity
5. Monitoring: Monitor webhook delivery success rates in GitHub