Skip to content

docs: Expand webhook documentation with comprehensive developer guide#680

Merged
cdecker merged 3 commits intomainfrom
cdecker/webhook-docs-expansion
Mar 4, 2026
Merged

docs: Expand webhook documentation with comprehensive developer guide#680
cdecker merged 3 commits intomainfrom
cdecker/webhook-docs-expansion

Conversation

@cdecker
Copy link
Collaborator

@cdecker cdecker commented Mar 3, 2026

Add extensive documentation covering:

  • Webhook types: per-node vs per-developer webhooks with use cases
  • Event types: invoice_payment and node_stuck with full payload schemas
  • Signature verification: examples in Python, Rust, and Node.js
  • Delivery guarantees: retry behavior with exponential backoff
  • Best practices: idempotency, async processing, security
  • Mermaid diagrams for webhook architecture and delivery flow

The documentation serves as the authoritative guide for developers integrating with Greenlight webhooks.

cdecker added 3 commits March 3, 2026 12:21
Add extensive documentation covering:
- Webhook types: per-node vs per-developer webhooks with use cases
- Event types: invoice_payment and node_stuck with full payload schemas
- Signature verification: examples in Python, Rust, and Node.js
- Delivery guarantees: retry behavior with exponential backoff
- Best practices: idempotency, async processing, security
- Mermaid diagrams for webhook architecture and delivery flow

The documentation serves as the authoritative guide for developers
integrating with Greenlight webhooks.
Create prestate_sketch from incoming state (nodelet's view) instead of
the signer's merged state. This ensures that initial VLS state created
during Signer::new() is properly sent back to the nodelet on the first
request, fixing the issue where nodes/, nodestates/, allowlists/, and
trackers/ entries were never synced to the tower.
@cdecker
Copy link
Collaborator Author

cdecker commented Mar 4, 2026

Additional Commit: VLS State Sync Fix

This PR now also includes a fix for test_tower_persists_signer_state CI failure.

Root Cause: The signer wasn't sending its initial VLS state to the nodelet/tower. It only sent diffs of what changed during each request, but the initial state (nodes/, nodestates/, allowlists/, trackers/) was created at startup during Signer::new(), not during request processing, so the diff was always empty.

Fix: Create prestate_sketch from the incoming state (nodelet's view) rather than the signer's merged state, ensuring any entries the nodelet doesn't have get sent back.

File: libs/gl-client/src/signer/mod.rs

Copy link
Collaborator

@ihordiachenko ihordiachenko left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The state sync fix looks good to me

@ihordiachenko ihordiachenko self-requested a review March 4, 2026 12:41
@cdecker cdecker merged commit 3ddf072 into main Mar 4, 2026
16 checks passed
@cdecker cdecker deleted the cdecker/webhook-docs-expansion branch March 4, 2026 13:16
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.

2 participants