Skip to content

Add webhook notification publisher for step/workflow status change events#228

Open
nikhiln64 wants to merge 1 commit into
Netflix:mainfrom
nikhiln64:feat/webhook-notification-publisher
Open

Add webhook notification publisher for step/workflow status change events#228
nikhiln64 wants to merge 1 commit into
Netflix:mainfrom
nikhiln64:feat/webhook-notification-publisher

Conversation

@nikhiln64

Copy link
Copy Markdown

Pull Request type

  • Bugfix
  • Feature
  • Refactoring (no functional changes, no api changes)
  • Build related changes (Please run ./gradlew build --write-locks to refresh dependencies)
  • Other (please describe):

NOTE: Please remember to run ./gradlew spotlessApply to fix any format violations.

Changes in this PR

Implements webhook support for step/workflow status change events, as requested in #111.

What it does: a new WebhookNotificationPublisher (maestro-engine, next to the existing publishers) POSTs the JSON-serialized MaestroEvent to a configured HTTP endpoint whenever the engine dispatches a notification job event. It plugs into the existing MaestroNotificationPublisher extension point, so NotificationJobEventProcessor and the event flow are untouched.

Configuration (mirrors the existing noop/sns conditional wiring):

maestro:
  notifier:
    type: webhook
    webhook:
      url: https://example.com/hooks/maestro
      event-types: [STEP_INSTANCE_STATUS_CHANGE_EVENT, WORKFLOW_INSTANCE_STATUS_CHANGE_EVENT]  # empty = all
      request-timeout-ms: 10000
      signing-secret: "..."   # optional

Design decisions:

  • Error classification over internal retries: follows the SNS publisher's contract - 4xx is thrown as MaestroUnprocessableEntityException (receiver rejected the payload; retrying the same request cannot help), 5xx and I/O failures throw MaestroRetryableError so the queue system drives retries. No second retry mechanism inside the publisher.
  • HMAC-SHA256 signing (optional): when signing-secret is set, requests carry X-Maestro-Signature-256: sha256=<hex> computed over the exact body bytes (GitHub-webhook style), so receivers can authenticate the sender. Without a secret the header is absent.
  • X-Maestro-Event-Type header lets receivers route cheaply without parsing the body.
  • JDK HttpClient: no new dependencies.

Testing: WebhookNotificationPublisherTest (6 tests) runs a real round-trip against a JDK HttpServer on an ephemeral port and verifies: payload round-trips as the same event, the signature matches the HMAC of the exact received bytes, no signature header without a secret, event-type filtering, 4xx → non-retryable, 5xx and connection failure → retryable. Full :maestro-engine:test and :maestro-server:test pass; spotlessApply run.

Developed with AI assistance (Claude Code), reviewed and driven by a human.

@nikhiln64
nikhiln64 force-pushed the feat/webhook-notification-publisher branch from 71a6a89 to 2da85a7 Compare July 14, 2026 14:01
@nikhiln64
nikhiln64 force-pushed the feat/webhook-notification-publisher branch from 2da85a7 to 9f775f7 Compare July 21, 2026 19:33
…ents

Implements the webhook support requested in Netflix#111. A new
WebhookNotificationPublisher POSTs the JSON-serialized MaestroEvent to a
configured endpoint, following the same error-classification contract as
the SNS publisher: 4xx responses are non-retryable (the receiver
rejected the payload), 5xx and I/O failures throw MaestroRetryableError
so the queue system retries delivery.

Features:
- event-type allowlist (empty = all event types)
- optional HMAC-SHA256 request signing via X-Maestro-Signature-256
  (GitHub-webhook style, sha256=<hex>), so receivers can authenticate
  the sender
- X-Maestro-Event-Type header for cheap receiver-side routing
- built on the JDK HttpClient: no new dependencies

Wired behind maestro.notifier.type=webhook with a
maestro.notifier.webhook.* properties block, mirroring the existing
noop/sns conditional wiring.
@nikhiln64
nikhiln64 force-pushed the feat/webhook-notification-publisher branch from 9f775f7 to b288579 Compare July 21, 2026 20:25
@nikhiln64

Copy link
Copy Markdown
Author

@jun-he the workflow run here is also waiting for approval. The branch is up to date with main and the full engine and server suites pass locally. Happy to adjust anything about the approach if you have thoughts on the webhook design.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant