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

# Register a webhook

> Register an HTTPS endpoint to receive signed event notifications when a workflow reaches a
terminal state. Halliday delivers each event as an HTTP `POST` to your registered `url`, so the
endpoint must accept `POST` requests. On success the response includes a `signing_secret` that
is **only ever returned on creation and rotation** — store it immediately, because it cannot be
retrieved again from the list endpoint.

Authenticate with a secret API key that has webhook access. Publishable keys cannot manage webhooks.




## OpenAPI

````yaml /public/openapi.yaml post /orgs/webhooks
openapi: 3.1.0
info:
  title: Halliday API V2
  description: >
    API V2 for Halliday's payment infrastructure, supporting onramps, swaps, and
    offramps.


    This API provides a unified interface for cryptocurrency payments, allowing
    developers to:

    - Quote payments across multiple providers

    - Execute payments with onramps, swaps, and offramps

    - Track payment status and history


    ## Authentication


    API key authentication is required for all endpoints.
  version: 2.0.0
  contact:
    name: Contact Halliday
    url: https://halliday.xyz
    email: support@halliday.xyz
servers:
  - url: https://v2.prod.halliday.xyz
    description: Base domain
security:
  - ApiKeyAuth: []
tags:
  - name: Chains
    description: Blockchain network information and configuration
  - name: Assets
    description: Asset information, discovery, and supported asset pairs
  - name: Payments
    description: >-
      Core payment operations including quotes, confirmation, and status
      tracking
  - name: Webhooks
    description: >
      Register HTTPS endpoints to receive signed notifications when a workflow
      reaches a terminal

      state, instead of polling for status. You subscribe to one or more event
      types per webhook.


      | Event type | Fires when a workflow's status becomes |

      | --- | --- |

      | `WORKFLOW_COMPLETED` | `COMPLETE` |

      | `WORKFLOW_FAILED` | `FAILED` |


      All management endpoints live under `/orgs/webhooks` and authenticate with
      a secret API key

      (passed as a bearer token) that has webhook access. Publishable keys
      cannot manage webhooks.


      **Integration checklist**


      - Receiver is a public HTTPS endpoint (no private IPs).

      - Save the `signing_secret` when you create the webhook — it is shown only
      once.

      - Verify `X-Halliday-Signature` against the raw body, accepting any of its
      comma-separated signatures.

      - Respond `2xx` quickly and do the real work afterward.

      - Skip deliveries whose `id` you have already handled.
paths:
  /orgs/webhooks:
    post:
      tags:
        - Webhooks
      summary: Register a webhook
      description: >
        Register an HTTPS endpoint to receive signed event notifications when a
        workflow reaches a

        terminal state. Halliday delivers each event as an HTTP `POST` to your
        registered `url`, so the

        endpoint must accept `POST` requests. On success the response includes a
        `signing_secret` that

        is **only ever returned on creation and rotation** — store it
        immediately, because it cannot be

        retrieved again from the list endpoint.


        Authenticate with a secret API key that has webhook access. Publishable
        keys cannot manage webhooks.
      operationId: registerWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterWebhookRequest'
            example:
              url: https://api.yourapp.com/halliday/webhooks
              label: prod-workflows
              event_types:
                - WORKFLOW_COMPLETED
                - WORKFLOW_FAILED
              auth_header:
                name: X-Webhook-Token
                value: a-shared-secret-token
      responses:
        '200':
          description: Webhook registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              example:
                id: 4f2c…
                label: prod-workflows
                url: https://api.yourapp.com/halliday/webhooks
                signing_secret: a1b2c3…
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              example:
                errors:
                  - code: invalid_type
                    expected: string
                    path:
                      - label
                    message: 'Invalid input: expected string, received undefined'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Invalid API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Publishable keys cannot manage webhooks
components:
  schemas:
    RegisterWebhookRequest:
      type: object
      required:
        - url
        - label
        - event_types
      properties:
        url:
          type: string
          format: uri
          description: >
            Receiver URL. Must be HTTPS on port 443. Private/reserved IP
            addresses are rejected (SSRF protection).
          example: https://api.yourapp.com/halliday/webhooks
        label:
          type: string
          description: >
            Human-readable identifier, unique per org. Used to address the
            webhook on update, rotate, and delete.
          example: prod-workflows
        event_types:
          type: array
          minItems: 1
          description: At least one event type to subscribe to.
          items:
            $ref: '#/components/schemas/WebhookEventType'
          example:
            - WORKFLOW_COMPLETED
            - WORKFLOW_FAILED
        auth_header:
          $ref: '#/components/schemas/WebhookAuthHeader'
        signing_secret:
          type: string
          description: >
            Optional. Provide your own HMAC-SHA256 signing secret instead of
            letting Halliday generate

            one. Omit this to receive a generated `signing_secret` in the
            response.
          example: my-own-signing-secret
    Webhook:
      type: object
      description: >
        A registered webhook including its signing secret. Returned only on
        creation and rotation.
      required:
        - id
        - label
        - url
        - signing_secret
      properties:
        id:
          type: string
          example: 4f2c…
        label:
          type: string
          example: prod-workflows
        url:
          type: string
          format: uri
          example: https://api.yourapp.com/halliday/webhooks
        signing_secret:
          type: string
          description: >
            HMAC-SHA256 signing secret. Store it now — it is never returned
            again from the list endpoint.
          example: a1b2c3…
    ValidationErrorResponse:
      type: object
      description: >
        Returned when a request body fails schema validation. `errors` contains
        one entry per

        validation issue.
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            type: object
            required:
              - code
              - path
              - message
            properties:
              code:
                type: string
                description: Validation issue code (for example `invalid_type`).
                example: invalid_type
              expected:
                type: string
                description: Expected type. Present on type-mismatch issues.
                example: string
              path:
                type: array
                description: Path to the offending field in the request body.
                items:
                  type:
                    - string
                    - integer
                example:
                  - label
              message:
                type: string
                example: 'Invalid input: expected string, received undefined'
    ErrorResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
      description: Error response for known errors
    WebhookEventType:
      type: string
      description: >
        Event type a webhook can subscribe to. `WORKFLOW_COMPLETED` fires when a
        workflow's status

        becomes `COMPLETE`; `WORKFLOW_FAILED` fires when it becomes `FAILED`.
      enum:
        - WORKFLOW_COMPLETED
        - WORKFLOW_FAILED
    WebhookAuthHeader:
      type: object
      description: >
        Optional custom HTTP header that Halliday attaches to every delivery to
        your receiver URL, so your

        endpoint can authenticate inbound deliveries in addition to verifying
        `X-Halliday-Signature`. The

        `value` is write-only — it is never returned by any endpoint; the list
        endpoint echoes only the

        header name as `auth_header_name`.
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: Header name Halliday sends on each delivery.
          example: X-Webhook-Token
        value:
          type: string
          description: Header value. Write-only — never returned.
          example: a-shared-secret-token
    Issue:
      oneOf:
        - $ref: '#/components/schemas/AmountIssue'
        - $ref: '#/components/schemas/AmountDownstreamIssue'
        - $ref: '#/components/schemas/FundingIssue'
        - $ref: '#/components/schemas/OwnerIssue'
        - $ref: '#/components/schemas/GeolocationIssue'
        - $ref: '#/components/schemas/ProviderIssue'
        - $ref: '#/components/schemas/PayinMethodIssue'
        - $ref: '#/components/schemas/OtherIssue'
        - $ref: '#/components/schemas/UnknownIssue'
      discriminator:
        propertyName: kind
    AmountIssue:
      type: object
      required:
        - kind
        - asset
        - given
        - limits
        - source
        - message
        - reason
      properties:
        kind:
          type: string
          enum:
            - amount
        asset:
          $ref: '#/components/schemas/Asset'
        given:
          $ref: '#/components/schemas/Amount'
        limits:
          $ref: '#/components/schemas/Limits'
        downstream_limits:
          $ref: '#/components/schemas/Limits'
        source:
          type: string
        message:
          type: string
        reason:
          type: string
          enum:
            - TOO_LOW
            - TOO_HIGH
            - NO_VALID_AMOUNT
            - UNKNOWN
    AmountDownstreamIssue:
      type: object
      required:
        - kind
        - asset
        - given
        - limits
        - source
        - message
        - reason
      properties:
        kind:
          type: string
          enum:
            - amount-downstream
        asset:
          $ref: '#/components/schemas/Asset'
        given:
          $ref: '#/components/schemas/Amount'
        limits:
          $ref: '#/components/schemas/Limits'
        downstream_limits:
          $ref: '#/components/schemas/Limits'
        source:
          type: string
        message:
          type: string
        reason:
          type: string
          enum:
            - TOO_LOW
            - TOO_HIGH
            - NO_VALID_AMOUNT
            - UNKNOWN
    FundingIssue:
      type: object
      required:
        - kind
        - token
        - balance
      properties:
        kind:
          type: string
          enum:
            - funding
        token:
          $ref: '#/components/schemas/Token'
        balance:
          type: string
          description: Current token balance at the funding address.
    OwnerIssue:
      type: object
      required:
        - kind
        - message
        - mitigation
      properties:
        kind:
          type: string
          enum:
            - owner
        message:
          type: string
        mitigation:
          type: string
          enum:
            - change
            - verify
    GeolocationIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - geolocation
        message:
          type: string
    ProviderIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - provider
        message:
          type: string
    PayinMethodIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - payin_method
        message:
          type: string
    OtherIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - other
        message:
          type: string
    UnknownIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - unknown
        message:
          type: string
    Asset:
      type: string
      description: >-
        Identifier in the token format ("chain:address") or fiat currency code
        ("USD")
      example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
    Amount:
      type: string
      description: A decimal amount string.
    Limits:
      type: object
      properties:
        min:
          type: string
          description: Minimum amount as a decimal string.
        max:
          type: string
          description: Maximum amount as a decimal string.
    Token:
      type: string
      description: Token identifier in the format "chain:address"
      pattern: ^[a-z]+:0x[a-fA-F0-9]+$
      example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY

````