Webhooks¶

Webhooks let your systems react in real time when resources change in PlusPlus — no polling required.

How webhooks work¶

1. You register a subscription with a target URL, an HMAC secret, and a list of event types.
2. When a matching event fires, PlusPlus POSTs a JSON payload to your URL with an X-Plusplus-Signature header.
3. Your endpoint verifies the signature, processes the event, and returns 2xx.
4. PlusPlus retries failures with exponential backoff for ~24 hours, then marks the delivery dead.

Event taxonomy¶

Naming follows {resource}.{action} (Stripe/GitHub-style).

Generic content events¶

Fired for every content type. Payload uses the shared ContentItemSummary schema.

Type-specific events¶

Fired alongside the generic event, with a richer, type-specific payload.

When an article is created, both content_item.created and article.created fire. Subscribe to whichever fits your needs (or both — events are deduplicated by id).

Assignment events¶

Wildcard subscriptions¶

You can subscribe with fnmatch-style globs:

• * — all events
• content_item.* — all generic content events
• article.* — all article-specific events
• assignment.* — all assignment events

Payload format¶

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "article.created",
  "api_version": "2.0.0",
  "created_at": "2026-04-06T12:00:00Z",
  "data": {
    "object": { /* same shape as GET response for that resource */ }
  }
}

data.object is identical to the GET response for that resource — no special parsing required.

Signature verification¶

Each delivery includes:

X-Plusplus-Signature: t=1714473600,v1=<hex_hmac>
X-Plusplus-Event: article.created
X-Plusplus-Event-Id: evt_a1b2c3d4-...

Verify the signature by computing HMAC-SHA256(secret, "{t}.{raw_body}") and comparing with v1 using a constant-time comparator. Reject deliveries where t is more than five minutes old to prevent replay.

Delivery semantics¶

• At-least-once. Use id to deduplicate.
• Retries. Exponential backoff up to ~24 hours total.
• Order. Deliveries are not strictly ordered. Use created_at if order matters.
• Timeout. Your endpoint must return 2xx within 10 seconds.

Security¶

• Target URLs must be https://.
• Private/internal IP ranges (10.x, 172.16.x, 192.168.x, 127.x, localhost) are rejected at registration.
• The HMAC secret is shown once at creation and rotation. Store it in a secret manager.

Subscription API¶

See the API reference for full request/response schemas once these endpoints ship.