Webhooks

Create webhook subscription

Register an HTTPS endpoint to receive real-time event notifications. Every delivery is signed with BeeL-Signature (HMAC-SHA256). The secret is returned once on creation — store it securely. Maximum 10 active webhook subscriptions per account.

POST
/v1/webhooks

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

Obtaining Keys: API Keys are managed from the BeeL dashboard

Security: API Keys are secret credentials. Do not share them or store them in source code

In: header

Request Body

urlstring

HTTPS endpoint URL that will receive webhook POST requests.

Formaturi
eventsarray<WebhookEventTypeEnum>

List of event types to subscribe to.

Items1 <= items

Response Body

application/json

application/json

application/json

application/json

Callbacks

curl -X POST "https://app.beel.es/api/v1/webhooks" \  -H "Content-Type: application/json" \  -d '{    "url": "https://yourapp.com/webhooks/beel",    "events": [      "verifactu.status.updated"    ]  }'
{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "url": "http://example.com",
    "events": [
      "string"
    ],
    "active": true,
    "last_used_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "secret": "whsec_a3f5b2e1c9d8f7e6b5a4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": {
      "field_name": "Field is required"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Update VeriFactu configuration PUT

Updates the user's VeriFactu configuration. **Business rules:** - If `enabled` is false, `apply_by_default` must also be false - If `apply_by_default` is true, `enabled` must be true

Delete webhook subscription DELETE

Permanently deletes a webhook subscription. No further events will be delivered.