Webhook Events

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

These are events Notra receives from GitHub. Notra does not emit its own webhook events; see No outbound webhooks for polling and streaming alternatives.

Processing order

Route check

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

Event type

X-GitHub-Event must be one of the four supported types, otherwise the delivery is logged and ignored.

Duplicate check

Deliveries with an X-GitHub-Delivery ID seen in the last 24 hours are skipped.

Signature

The body is verified against the repository’s secret using X-Hub-Signature-256.

Filter

Each event type has its own rules (below). Events that do not pass are logged as filtered and return 200.

Dispatch

Push and release events are saved as context for chat and matched against your event triggers. Merged pull requests are recorded as signals for Iris.

Push

Sent when commits are pushed 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

Pushes to other branches, tag pushes, and empty pushes (for example a branch deletion) are filtered.

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

Sent 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

created, edited, deleted, released, and unpublished actions are filtered. Draft releases never pass, so publishing a draft is processed 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

Sent when a pull request is opened, closed, or updated. Notra only keeps merges.

string

required

pull_request

string

required

merged

Filtering

GitHub’s action is closed

pull_request.merged is true

Opened, synchronized, and closed-without-merge pull requests are filtered.

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;
  };
}

Merged pull requests feed Iris signals only. They are not stored as chat context and do not fire event triggers; event triggers can only subscribe to push and release.

Ping

Sent by GitHub when you save the webhook or click Redeliver on the ping in your webhook settings.

string

required

ping

Ping deliveries are signature-checked, logged, and answered with:

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

They do not trigger any workflow.

Event triggers

Push and release events are matched 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. Triggers created through the API must list at least one.
includePreReleases defaults to true. When false, prereleased events are skipped for that trigger.
Each matching trigger starts one generation run per delivery. The run is keyed 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. 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; 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

For processed events: event, action, and the processed data. For filtered events: event, action, and filtered: true. For unsupported event types: 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

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