Module octocrab::models::webhook_events

source ·
Expand description

Serde mappings from GitHub’s Webhook payloads to structs.

Github Applications can be written as simple servers (using e.g. Axum), and then deserialize the webhook payloads it receives thanks to the models included in this module.

The main entry point is to read the “event type” from the HTTP request header sent by github (at time of writing, the header is named X-GitHub-Event) and then pass the value, along with the payload, to WebhookEvent::try_from_header_and_body which will validate the payload and return a valid WebhookEvent.

use octocrab::models::{AppId, webhook_events::{WebhookEvent, WebhookEventPayload, WebhookEventType}};

let json = r#"{
  "zen": "Design for failure.",
  "hook_id": 423885699,
  "hook": {
    "type": "App",
    "id": 423885699,
    "name": "web",
    "active": true,
    "events": [
      "issues",
      "issue_comment",
      "meta",
      "pull_request",
      "pull_request_review",
      "pull_request_review_comment",
      "pull_request_review_thread",
      "repository"
    ],
    "config": {
      "content_type": "json",
      "insecure_ssl": "0",
      "secret": "********",
      "url": "https://smee.io/R"
    },
    "updated_at": "2023-07-13T09:30:45Z",
    "created_at": "2023-07-13T09:30:45Z",
    "app_id": 360617,
    "deliveries_url": "https://api.github.com/app/hook/deliveries"
  }
}"#;

// Value picked from the `X-GitHub-Event` header
let event_name = "ping";

let event = WebhookEvent::try_from_header_and_body(event_name, json)?;
assert_eq!(event.kind, WebhookEventType::Ping);
let WebhookEventPayload::Ping(ping_event) = event.specific else { panic!("checked for event.kind type before unwrapping") };
assert_eq!(ping_event.hook.unwrap().app_id.unwrap(), AppId(360617));

§Stability

The GitHub API for webhooks is not stable, nor specified as far as we know. Therefore, any contribution to provide more precise structures for payloads, with some actual example values to test, is very welcome.

This also means you should consider octocrab’s support for webhooks in beta state: it is usable, but the API needs to change according to actual usage in order to refine the different payloads received.

Re-exports§

Modules§

Structs§

Enums§