Webhook events

Notra accepts only four GitHub event types on its webhook endpoint: ping, push, release and pull_request. Notra acknowledges every other event type with 200 and "ignored": true so GitHub does not retry it, and does nothing else with it.

These are events Notra receives from GitHub. For signed post lifecycle, generation and GEO scan events sent to your endpoint, see Outbound webhooks.

Processing order

Route check

The organization, integration and repository IDs in the payload URL must exist and belong together, and the integration must be enabled.

Event type

X-GitHub-Event must be one of the four supported types, otherwise Notra logs and ignores the delivery.

Duplicate check

Notra skips deliveries with an X-GitHub-Delivery ID it has seen in the last 24 hours.

Signature

Notra verifies the body against the repository’s secret using X-Hub-Signature-256.

Filter

Each event type has its own rules, described below. Notra logs events that do not pass as filtered and returns 200.

Dispatch

Notra saves push and release events as context for chat and matches them against your event triggers, while it records merged pull requests for internal use.

Push

GitHub sends this event when someone pushes commits to the repository.

string

required

push

string

required

pushed

Filtering

A push is processed only when both conditions hold:

ref is the repository’s default branch (refs/heads/{default_branch})

The payload contains at least one commit

Notra filters pushes to other branches, tag pushes and empty pushes (for example a branch deletion).

Processed payload

This is the shape Notra passes to event triggers and returns under processed in the webhook response.

{
  "type": "push",
  "action": "pushed",
  "data": {
    "ref": "refs/heads/main",
    "branch": "main",
    "commits": [
      {
        "id": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
        "message": "Add new feature",
        "author": {
          "name": "Jane Developer",
          "email": "jane@example.com",
          "username": "janedev"
        },
        "timestamp": "2026-09-01T10:30:00Z",
        "url": "https://github.com/owner/repo/commit/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"
      }
    ],
    "headCommit": {
      "id": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
      "message": "Add new feature"
    }
  }
}

interface PushEvent {
  type: "push";
  action: "pushed";
  data: {
    ref: string;
    branch: string;
    commits: Array<{
      id: string;
      message: string;
      author: { name: string; email: string; username?: string };
      timestamp: string;
      url: string;
    }>;
    headCommit: { id: string; message: string } | null;
  };
}

Release

GitHub sends this event when a release changes state.

string

required

release

string

required

published or prereleased

Filtering

GitHub’s action is published or prereleased

The release is not a draft

Notra filters created, edited, deleted, released and unpublished actions. Draft releases never pass, so Notra processes a published draft once, when GitHub sends published.

Processed payload

{
  "type": "release",
  "action": "published",
  "data": {
    "tagName": "v1.2.0",
    "name": "Version 1.2.0",
    "body": "## What's Changed\n- New feature X\n- Bug fix Y",
    "prerelease": false,
    "draft": false,
    "publishedAt": "2026-09-01T14:30:00Z",
    "url": "https://github.com/owner/repo/releases/tag/v1.2.0"
  }
}

interface ReleaseEvent {
  type: "release";
  action: "published" | "prereleased";
  data: {
    tagName: string;
    name: string | null;
    body: string | null;
    prerelease: boolean;
    draft: boolean;
    publishedAt: string | null;
    url: string;
  };
}

Pull request

GitHub sends this event when a pull request is opened, closed or updated, but Notra only keeps merges.

string

required

pull_request

string

required

merged

Filtering

GitHub’s action is closed

pull_request.merged is true

Notra filters opened, synchronized and closed-without-merge pull requests.

Processed payload

{
  "type": "pull_request",
  "action": "merged",
  "data": {
    "number": 842,
    "title": "Add webhook retries",
    "body": "Adds exponential backoff to delivery.",
    "url": "https://github.com/owner/repo/pull/842",
    "mergedAt": "2026-09-01T09:12:00Z",
    "mergeCommitSha": "0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d",
    "author": "janedev",
    "baseBranch": "main"
  }
}

interface PullRequestEvent {
  type: "pull_request";
  action: "merged";
  data: {
    number: number;
    title: string;
    body: string | null;
    url: string;
    mergedAt: string | null;
    mergeCommitSha: string | null;
    author: string | null;
    baseBranch: string | null;
  };
}

Notra does not store merged pull requests as chat context, and they do not fire event triggers because event triggers can only subscribe to push and release.

Ping

GitHub sends this event when you save the webhook or click Redeliver on the ping in your webhook settings.

string

required

ping

Notra checks the signature of each ping delivery, logs it and answers with:

{
  "message": "Pong! Webhook configured successfully",
  "event": "ping",
  "delivery": "12345678-1234-1234-1234-123456789abc"
}

Pings do not trigger any workflow.

Event triggers

Notra matches push and release events against enabled event triggers whose targets include the repository. The trigger’s sourceConfig decides which events fire it:

{
  "sourceType": "github_webhook",
  "sourceConfig": {
    "eventTypes": ["push", "release"],
    "includePreReleases": true
  }
}

{
  "sourceType": "github_webhook",
  "sourceConfig": {
    "eventTypes": ["release"],
    "includePreReleases": false
  }
}

eventTypes accepts push and release, and triggers created through the API must list at least one.
includePreReleases defaults to true, and when it is false the trigger skips prereleased events.
Each matching trigger starts one generation run per delivery. Notra keys the run by trigger ID and delivery ID, so a redelivered event does not start a second run.

See Event triggers for creating and managing triggers in the dashboard.

Log entries

Each delivery writes one entry to Settings, then Logs, where the integrationType is github, direction is incoming and referenceId is the X-GitHub-Delivery ID.

string

required

What happened, for example Processed release event, Filtered push event, Unsupported event type: issues, Invalid webhook signature or Webhook ping received

string

required

success for processed, filtered, ignored and ping deliveries and failed for rejected ones

number

The HTTP status Notra returned to GitHub

string

Set on failed entries, for example Missing X-Hub-Signature-256 header

object

Processed events include event, action and the processed data, filtered events include event, action and filtered: true, and unsupported event types include event and ignored: true.

{
  "id": "log_a1b2c3d4",
  "referenceId": "12345678-1234-1234-1234-123456789abc",
  "title": "Processed push event",
  "integrationType": "github",
  "direction": "incoming",
  "status": "success",
  "statusCode": 200,
  "errorMessage": null,
  "payload": {
    "event": "push",
    "action": "pushed",
    "data": {
      "ref": "refs/heads/main",
      "branch": "main",
      "commits": [
        {
          "id": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d",
          "message": "Add new feature",
          "author": { "name": "Jane Developer", "email": "jane@example.com", "username": "janedev" },
          "timestamp": "2026-09-01T10:30:00Z",
          "url": "https://github.com/owner/repo/commit/7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"
        }
      ],
      "headCommit": { "id": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d", "message": "Add new feature" }
    }
  },
  "createdAt": "2026-09-01T10:30:00.000Z"
}

{
  "id": "log_x9y8z7w6",
  "referenceId": "87654321-4321-4321-4321-cba987654321",
  "title": "Invalid webhook signature",
  "integrationType": "github",
  "direction": "incoming",
  "status": "failed",
  "statusCode": 401,
  "errorMessage": "Invalid webhook signature",
  "payload": null,
  "createdAt": "2026-09-01T10:35:00.000Z"
}

{
  "id": "log_m5n6o7p8",
  "referenceId": "11112222-3333-4444-5555-666677778888",
  "title": "Filtered push event",
  "integrationType": "github",
  "direction": "incoming",
  "status": "success",
  "statusCode": 200,
  "errorMessage": null,
  "payload": { "event": "push", "action": "", "filtered": true },
  "createdAt": "2026-09-01T10:40:00.000Z"
}

Getting Started

Developer Tools

Guides

Webhooks

Endpoints

Processing order

Push

Filtering

Processed payload

Release

Filtering

Processed payload

Pull request

Filtering

Processed payload

Ping

Event triggers

Log entries

Next steps

Webhooks overview

Configure triggers

​Processing order

​Push

​Filtering

​Processed payload

​Release

​Filtering

​Processed payload

​Pull request

​Filtering

​Processed payload

​Ping

​Event triggers

​Log entries

​Next steps

Webhooks overview

Configure triggers

Processing order

Push

Filtering

Processed payload

Release

Filtering

Processed payload

Pull request

Filtering

Processed payload

Ping

Event triggers

Log entries

Next steps