openapi: 3.0.3
info:
    title: webhooks
    description: The Webhooks service listens to pub/sub topics for platform events and forwards them to client systems. It ensures clients receive real-time notifications via their configured webhook URLs.
    version: 1.0.0
servers:
    - url: https://webhooks.platform.arb.inc
paths:
    /:
        get:
            summary: Get basic service information
            description: Returns a plain text welcome message with the service name and creation date.
            operationId: getRoot
            responses:
                '200':
                    description: Successfully retrieved welcome message.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Welcome to the webhooks service. Created on August 25, 2025 by Al Beebe
            tags:
                - /
    /urls/delete:
        post:
            summary: Delete a webhook URL
            description: Removes a registered webhook URL from the organization.
            operationId: deleteURL
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - url
                            properties:
                                url:
                                    type: string
                                    description: The webhook URL to delete.
                                    example: "https://example.com/webhook"
            responses:
                '200':
                    description: URL successfully deleted.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: URL successfully deleted
                '404':
                    description: URL not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: url not found
                '410':
                    description: Only organizations can use webhooks.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Webhooks are only available to organizations
            tags:
                - urls
    /urls/list:
        post:
            summary: List registered webhook URLs
            description: Returns all webhook URLs saved for your organization.
            operationId: postURLsList
            security:
                - bearerAuth: []
            responses:
                '200':
                    description: URLs successfully retrieved.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    urls:
                                        type: array
                                        description: List of webhook URLs.
                                        items:
                                            type: object
                                            properties:
                                                created:
                                                    type: string
                                                    format: date-time
                                                    description: UTC timestamp when the webhook URL was created.
                                                    example: "2025-01-15T14:23:45Z"
                                                createdBy:
                                                    type: string
                                                    description: User that registered the webhook.
                                                    example: "e1f8b6a2-6b3a-4c2d-9a1f-0bbd9f4b12cd"
                                                url:
                                                    type: string
                                                    format: uri
                                                    description: The webhook callback URL registered by the client.
                                                    example: "https://example.com/webhooks/orders"
                                example:
                                    urls:
                                        - created: "2025-01-15T14:23:45Z"
                                          createdBy: "e1f8b6a2-6b3a-4c2d-9a1f-0bbd9f4b12cd"
                                          url: "https://example.com/webhooks/orders"
                                        - created: "2025-02-03T09:10:11Z"
                                          createdBy: "a3c9de77-1b52-4b4f-93d9-bc2f7aa43f0e"
                                          url: "https://api.partner.io/hooks/invoice-updates"
                '410':
                    description: User is not part of an organization.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "Webhooks are only available to organizations"
            tags:
                - urls
    /urls/register:
        post:
            summary: Register a webhook URL
            description: Adds a webhook URL for the signed-in user and their org.
            operationId: registerWebhookURL
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - url
                            properties:
                                url:
                                    type: string
                                    description: The webhook URL to register. Max 500 characters.
                                    maxLength: 2048
                                    example: "https://example.com/webhooks/ingest"
            responses:
                '200':
                    description: URL registered.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: url successfully registered
                '410':
                    description: User is not part of an organization.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Webhooks are only available to organizations
                '411':
                    description: URL registration limit reached.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: limit reached
                '412':
                    description: URL already registered.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: url has already been registered
            tags:
                - urls
    /urls/test:
        post:
            summary: Send a test webhook
            description: Triggers a test webhook to a registered URL.
            operationId: postURLsTest
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - url
                            properties:
                                url:
                                    type: string
                                    format: uri
                                    description: The webhook URL to test.
                                    example: https://hooks.example.com/order-updates
            responses:
                '200':
                    description: Test webhook executed and result returned.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    statusCode:
                                        type: integer
                                        description: HTTP status code returned by the webhook endpoint.
                                        example: 202
                                    body:
                                        type: string
                                        description: Raw response body from the webhook endpoint (truncated to 1kb).
                                        example: "success!"
                '404':
                    description: The URL is not registered.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: url is not registered
                '410':
                    description: Webhooks are only available to organizations.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Webhooks are only available to organizations
                '411':
                    description: Request timed out.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Request timed out
            tags:
                - urls
components:
    securitySchemes:
        bearerAuth:
            type: http
            description: access token
            scheme: bearer
            bearerFormat: JWT
tags:
    - name: /
    - name: urls