> ## Documentation Index > Fetch the complete documentation index at: https://docs.auth.energy/llms.txt > Use this file to discover all available pages before exploring further. # Register a webhook endpoint > Registers (or replaces) the HTTPS URL to which the supplier will deliver event notifications. Each RTI User has one active webhook URL per supplier. ## OpenAPI ````yaml /tariff-interop/api/openapi-tariff.yaml post /v1/webhook openapi: 3.1.0 info: title: Tariff Interoperability API version: 0.1.1.AE description: > The Tariff Interoperability (TI) API lets Energy Smart Appliances, optimisers, and third-party services access standardised electricity tariff pricing data directly from GB energy suppliers. It is defined under the Retail Energy Code (REC) and mandated by the Smart Secure Electricity Systems (SSES) Programme. ## Two tiers of access | Tier | Who can use it | Auth required | |------|---------------|---------------| | **Public Tariff Pricing Data** | Any TI User | None | | **Consumer Specific Tariff Information** | Registered TI Users (RTI Users) with active consumer consent | OAuth 2.0 | contact: name: Auth Energy email: contact@auth.energy license: name: | © 2025 Retail Energy Code Company Ltd v0.1.0. All modifications and improves published © 2026 Auth Energy Ltd url: https://auth.energy/ servers: - url: https://register.tariff.interop description: > Central TI Register hosted by RECCo. Serves the `/v1/suppliers` and `/v1/users` endpoints only. The `v1` path prefix identifies the API version. - url: https://example-supplier.co.uk description: > Placeholder for a TI Energy Supplier's own hosted API. Each supplier runs their own instance at a URL they register with RECCo — discover it from `GET /suppliers`. Serves all `/v1/tariff`, `/v1/consent`, `/v1/webhook`, `/v1/report`, and outbound webhook endpoints. security: [] tags: - name: Registry description: >- Discover active suppliers and registered third-party users. Served by the central RECCo register. No authentication required for public data. - name: Tariffs description: >- Retrieve tariff listings and full pricing detail from a specific supplier. No authentication required. - name: Consumer Tariffs description: >- Retrieve tariff data tied to a specific consumer metering point. Requires OAuth 2.0 and active consumer consent. - name: Consent description: >- Register and revoke consumer consent linking a metering point to an RTI User via the OAuth 2.0 Authorisation Code flow. - name: Webhooks description: >- Manage webhook endpoints and receive push notifications when tariff data or consent state changes. - name: Reporting description: >- Submit periodic performance assurance metrics to RECCo (supplier obligation). paths: /v1/webhook: post: tags: - Webhooks summary: Register a webhook endpoint description: > Registers (or replaces) the HTTPS URL to which the supplier will deliver event notifications. Each RTI User has one active webhook URL per supplier. operationId: registerWebhook requestBody: required: true content: application/json: schema: type: object required: - webhook_url properties: webhook_url: type: string format: uri description: The HTTPS URL that will receive event notification POSTs. example: webhook_url: https://my-optimiser.example.com/hooks/tariff-events responses: '201': description: Webhook registered. Returns the assigned webhook ID. content: application/json: schema: type: object properties: webhook_id: $ref: '#/components/schemas/WebhookId' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' security: - oauth2AuthCode: - tariff:webhook servers: - url: https://example-supplier.co.uk description: TI Energy Supplier API components: schemas: WebhookId: type: string format: uuid description: UUID uniquely identifying a registered webhook endpoint. example: 550e8400-e29b-41d4-a716-446655440000 ErrorResponse: type: object required: - code - message properties: code: type: string description: Machine-readable error code. example: tariff_not_found message: type: string description: Human-readable error description. example: No tariff found for the given tariff_id and supplier MPID. details: type: string description: Additional context to help diagnose the issue. example: >- tariff_id a1b2c3d4-e5f6-7890-abcd-ef1234567890 does not exist for supplier SEBD. responses: BadRequest: description: >- 400 — Request does not match the required format or references an out-of-scope tariff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: 401 — Missing or invalid authentication credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: 500 — Unexpected server error. Retry within the 72-hour buffer window. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: oauth2AuthCode: type: oauth2 description: > OAuth 2.0 Authorisation Code flow for RTI User authentication and consumer consent. Each supplier operates its own OAuth server. In production, substitute the placeholder host with the relevant `url` from the Supplier Register. OpenAPI does not permit URI templates in security scheme URLs, so a placeholder is used here. flows: authorizationCode: authorizationUrl: https://example-supplier.co.uk/oauth2/authorize tokenUrl: https://example-supplier.co.uk/oauth2/token scopes: tariff:read:consumer: Read consumer-specific tariff data for consented metering points. tariff:register: Register and revoke consumer consent relationships. tariff:webhook: Register and manage webhook endpoints. ````