> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Royalty file status update webhook

> Receives status updates for royalty file processing from Google Cloud Functions or external processing systems.

<Note>
  This endpoint requires authentication. Include your Bearer token in the Authorization header.
</Note>

## Description

**Authentication:** Requires `royalti-x-hash` header containing HMAC signature.

**Workflow:**

1. Validates file exists and belongs to tenant
2. Invalidates accounting cache
3. Sends notification to tenant admins (if status is 'processed')
4. Records Stripe usage meter event for billing
5. Queues stats and accounting pipeline jobs

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://api.royalti.io/webhook/royalty/file-update/webhook', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "tenant": 123
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
    'https://api.royalti.io/webhook/royalty/file-update/webhook',
    headers={
      'Authorization': f'Bearer {token}'
    },
    json={"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","tenant":123}
  )

  data = response.json()
  print(data)
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.royalti.io/webhook/royalty/file-update/webhook \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","tenant":123}'

  ```
</CodeGroup>


## OpenAPI

````yaml post /webhook/royalty/file-update/webhook
openapi: 3.0.0
info:
  title: Royalti.io API
  description: "# Royalti API\r\n\r\nThis is the Royalti music royalty management platform API server.\r\n\r\n## Overview\r\n\r\nThe Royalti API provides comprehensive music royalty management services including:\r\n- Music publishing and writer management\r\n- Royalty processing and analytics\r\n- DDEX integration for music industry standards\r\n- File processing and pattern recognition\r\n- Payment processing and distribution\r\n\r\n## Authentication\r\n\r\nThe API uses JWT-based authentication with multiple protection levels:\r\n- Public endpoints for basic operations\r\n- Protected endpoints requiring valid JWT tokens\r\n- Admin endpoints for administrative functions\r\n\r\n## Features\r\n\r\n- Multi-dimensional royalty analytics\r\n- CWR (Collective Works Registration) support\r\n- DDEX integration for music metadata\r\n- Advanced file processing with pattern recognition\r\n- Real-time data processing with queue system"
  version: 2.6.0
  contact:
    name: Royalti.io Support
    email: support@royalti.io
    url: https://royalti.io
  license:
    name: Proprietary
    url: https://royalti.io/terms
servers:
  - url: https://api.royalti.io
    description: Production server
  - url: https://api-dev.royalti.io
    description: Development server
  - url: http://localhost:8084
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Accounting
    description: Accounting and financial transaction operations
  - name: DDEX
    description: DDEX operations (ERN/MEAD, messages, delivery, providers)
  - name: Label
    description: Label management operations
  - name: Internal Webhooks
    description: Internal system webhooks for royalty processing and downloads
  - name: Payment Webhooks
    description: Payment processor webhook endpoints
  - name: Billing Webhooks
    description: Stripe billing and subscription webhooks
  - name: Infrastructure Webhooks
    description: Cloudflare domain and SSL webhooks
  - name: Distribution Webhooks
    description: Digital distribution platform webhooks (FUGA)
paths:
  /webhook/royalty/file-update/webhook:
    post:
      tags:
        - Internal Webhooks
      summary: Royalty file status update webhook
      description: >-
        Receives status updates for royalty file processing from Google Cloud
        Functions or external processing systems.


        **Authentication:** Requires `royalti-x-hash` header containing HMAC
        signature.


        **Workflow:**

        1. Validates file exists and belongs to tenant

        2. Invalidates accounting cache

        3. Sends notification to tenant admins (if status is 'processed')

        4. Records Stripe usage meter event for billing

        5. Queues stats and accounting pipeline jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - tenant
              properties:
                id:
                  type: string
                  format: uuid
                  description: File UUID from the File table
                  example: f47ac10b-58cc-4372-a567-0e02b2c3d479
                tenant:
                  type: integer
                  description: Tenant ID that owns the file
                  example: 123
      responses:
        '200':
          description: Webhook processed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: File status updated successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: error
                  message:
                    type: string
                    example: File Upload Record not found
      security:
        - RoyaltiWebhookAuth: []
components:
  responses:
    BadRequestError:
      description: Bad request - Invalid payload or validation error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              message:
                type: string
                example: Invalid request data
    UnauthorizedError:
      description: Unauthorized - Invalid or missing authentication
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              message:
                type: string
                example: Invalid webhook signature
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT Authorization header using the Bearer scheme. Format: "Bearer
        {token}"

````