Add to Cursor Add to Claude Copy for LLM View as MD

GitHub Webhooks

GitHub can send webhooks for repository events — pushes, pull requests, issues, releases, and so on. This guide walks through connecting GitHub webhooks to Hatchet.

Setup

Create the webhook in Hatchet

In the Hatchet dashboard, go to Webhooks and create a new webhook with the following settings:

Field	Value
Name	`github` (or whatever you’d like)
Source	GitHub
Event Key Expression	`'github:' + headers['x-github-event'] + ':' + input.action`
Secret	A secret string of your choosing (you’ll use the same one in GitHub)

A quick note on the event key expression: GitHub sends the event type (like pull_request or issues) in the x-github-event header, and the specific action (like opened or closed) in the payload’s action field. The expression above combines them to produce keys like github:pull_request:opened.

Not all GitHub events have an action field, though. Push events, for instance, don’t. If you want to handle events that might not have an action, you could use a simpler expression like 'github:' + headers['x-github-event'] and handle action-level routing in your task logic instead. Or you could create two separate webhooks — one for action-based events and one for action-less events.

Once you’ve created the webhook, copy the URL.

Configure the webhook in GitHub

Go to your repository (or organization) settings, find Webhooks, and add a new webhook. See GitHub’s webhook docs for the full walkthrough.

Payload URL: Paste the Hatchet webhook URL.
Content type: Select application/json.
Secret: Enter the same secret you used when creating the webhook in Hatchet.
Events: Choose “Let me select individual events” and pick the ones you care about, or select “Send me everything” if you prefer.

⚠️

Make sure you set the content type to application/json. GitHub defaults to application/x-www-form-urlencoded, which won’t work with Hatchet’s JSON payload parsing.

Write a task that listens for GitHub events

Here’s an example that triggers when a pull request is opened:

examples/python/webhooks/worker.py

class GitHubPullRequest(BaseModel):
    number: int
    title: str


class GitHubRepository(BaseModel):
    full_name: str


class GitHubPRInput(BaseModel):
    action: str
    pull_request: GitHubPullRequest
    repository: GitHubRepository


class GitHubPROutput(BaseModel):
    repo: str
    pr: int


@hatchet.task(
    input_validator=GitHubPRInput,
    on_events=["github:pull_request:opened"],
)
def handle_github_pr(input: GitHubPRInput, ctx: Context) -> GitHubPROutput:
    repo = input.repository.full_name
    pr_number = input.pull_request.number
    title = input.pull_request.title
    print(f"PR #{pr_number} opened on {repo}: {title}")
    return GitHubPROutput(repo=repo, pr=pr_number)

examples/typescript/webhooks/workflow.ts

type GitHubPRInput = {
  action: string;
  pull_request: {
    number: number;
    title: string;
  };
  repository: {
    full_name: string;
  };
};

export const handleGitHubPR = hatchet.task({
  name: 'handle-github-pr',
  on: {
    event: 'github:pull_request:opened',
  },
  fn: async (input: GitHubPRInput) => {
    const repo = input.repository.full_name;
    const prNumber = input.pull_request.number;
    const { title } = input.pull_request;
    console.log(`PR #${prNumber} opened on ${repo}: ${title}`);
    return { repo, pr: prNumber };
  },
});

examples/go/webhooks/main.go

type GitHubPRInput struct {
	Action      string `json:"action"`
	PullRequest struct {
		Number int    `json:"number"`
		Title  string `json:"title"`
	} `json:"pull_request"`
	Repository struct {
		FullName string `json:"full_name"`
	} `json:"repository"`
}

githubPR := client.NewStandaloneTask(
	"handle-github-pr",
	func(ctx hatchet.Context, input GitHubPRInput) (*struct {
		Repo string `json:"repo"`
		PR   int    `json:"pr"`
	}, error) {
		fmt.Printf("PR #%d opened on %s: %s\n", input.PullRequest.Number, input.Repository.FullName, input.PullRequest.Title)
		return &struct {
			Repo string `json:"repo"`
			PR   int    `json:"pr"`
		}{
			Repo: input.Repository.FullName,
			PR:   input.PullRequest.Number,
		}, nil
	},
	hatchet.WithWorkflowEvents("github:pull_request:opened"),
)

The Ruby SDK is in early access, and may change. We'd love your feedback!

examples/ruby/webhooks/worker.rb

HANDLE_GITHUB_PR = HATCHET.task(
  name: "handle-github-pr",
  on_events: ["github:pull_request:opened"]
) do |input, ctx|
  repo = input["repository"]["full_name"]
  pr_number = input["pull_request"]["number"]
  title = input["pull_request"]["title"]
  puts "PR ##{pr_number} opened on #{repo}: #{title}"
  { "repo" => repo, "pr" => pr_number }
end

Test it

After saving the webhook in GitHub, GitHub will send a ping event to verify the connection. You can also use the “Redeliver” button in GitHub’s webhook settings to replay past events, or just open a PR to trigger a real event.

Stripe Slack

We use cookies