Webhooks¶

Webhooks let you subscribe to platform events and receive HTTP POST notifications to a URL you configure. The primary current use case is container image push events from the b'nerd registry, which trigger automatic app reconciliation.

Endpoints¶

Creating a webhook¶

POST /webhooks
Authorization: Bearer <token>
Content-Type: application/json

{
  "webhook": {
    "name": "my-registry-hook",
    "url": "https://hooks.example.com/bnerd"
  }
}

Returns 201 Created with the webhook object including its id. Configure your registry or external system to POST to /webhooks/{id}/receive.

Inbound event format¶

The /webhooks/{id}/receive endpoint is public (no authentication required) so external systems can deliver events without a b'nerd token. The platform currently processes container registry push events:

{
  "type": "PUSH_ARTIFACT",
  "occur_at": 1710412477,
  "operator": "robot$myapp+deploy",
  "event_data": {
    "resources": [
      {
        "digest": "sha256:abc123...",
        "tag": "1.2.3",
        "resource_url": "registry.bnerd.com/myorg/myapp:1.2.3"
      }
    ],
    "repository": {
      "name": "myapp",
      "namespace": "myorg",
      "repo_full_name": "myorg/myapp"
    }
  }
}

When the resource_url in event_data.resources[0] matches a webhook target mapping, the corresponding app is reconciled automatically.

Authorization¶

• Management endpoints (GET, POST, PATCH, DELETE on /webhooks/*) require a valid Authorization: Bearer header.
• The receive endpoint (POST /webhooks/{id}/receive) is intentionally unauthenticated to allow the registry to POST without a b'nerd token.