> For the complete documentation index, see [llms.txt](https://docs.violetlabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violetlabs.com/features/api/outbound-webhooks/openapi-spec.md).

# OpenAPI spec

The request Violet sends to your endpoint, as an OpenAPI 3.1 webhooks document.

Import this spec into your API tooling or generate receiver types from it. The [Payload reference](https://docs.violetlabs.com/features/api/outbound-webhooks/payload-reference) page renders it, and you can download it from [openapi.gitbook.com](https://openapi.gitbook.com/o/lYcjJh2JWTqyhBJIaiRt/spec/violet-outbound-webhooks.yaml).

```yaml
openapi: 3.1.0
info:
  title: Violet outbound webhooks
  version: 1.0.0
  summary: The request Violet sends to your webhook endpoint.
  description: |
    Violet sends a signed, batched JSON `POST` to your HTTPS endpoint when
    watched entities change. Payloads carry ids only; read details through the
    Violet API with an API key.

    Verify `Violet-Signature` against the raw body before parsing: `v1` is a
    hex HMAC-SHA256 of `<t>.<raw body>`, keyed with the webhook's signing
    secret (including its `whsec_` prefix). Accept the request if any `v1`
    matches.

    Delivery is at least once and in order per webhook. Deduplicate by
    `eventId` and by `Violet-Delivery-Id`.
  contact:
    name: Violet Labs
    url: https://docs.violetlabs.com
servers:
  - url: https://{yourEndpoint}
    description: Your receiver. Violet posts to the endpoint URL configured on the webhook.
    variables:
      yourEndpoint:
        default: example.com/hooks/violet
tags:
  - name: Outbound webhooks
    description: Requests Violet sends to your endpoint.
security:
  - violetSignature: []
webhooks:
  violetEvents:
    post:
      operationId: receiveVioletWebhook
      tags: [Outbound webhooks]
      summary: A batch of change events
      description: |
        Sent to the endpoint URL configured on the webhook. One request carries
        1 to 500 events, all from the same source system. Respond with any 2xx
        within 10 seconds.
      parameters:
        - name: Violet-Signature
          in: header
          required: true
          description: |
            `t=<unix seconds>,v1=<hex>[,v1=<hex>]`. `t` is the time of this
            attempt and changes on every retry. During the 24 hours after a
            secret rotation there are two `v1` values (new and old secret).
          schema:
            type: string
            pattern: '^t=\d+(,v1=[0-9a-f]{64})+$'
          example: t=1792951514,v1=8f3a0c5e7b1d9f2a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a
        - name: Violet-Delivery-Id
          in: header
          required: true
          description: The delivery's id; equal to `deliveryId` in the body and the same on every retry.
          schema:
            type: string
            format: uuid
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
            const: Violet-Webhooks/1.0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
            examples:
              entityUpdated:
                summary: Entity events on a linked webhook
                value:
                  deliveryId: 0199e3c6-4f2a-7b1c-8d3e-5f6a7b8c9d0e
                  timestamp: '2026-10-20T18:05:14.020Z'
                  source: teamcenter
                  subscriptionId: 0199e3c4-1d2e-7f3a-8b4c-5d6e7f8a9b0c
                  events:
                    - eventId: 0199e3c5-8a1b-7c2d-9e3f-0a1b2c3d4e5f
                      type: entity.updated
                      occurredAt: '2026-10-20T18:04:12.511Z'
                      entityId: 0198aa10-3c4d-7e5f-8a6b-7c8d9e0f1a2b
                      integrationId: 0197ff02-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                      entityType: Part Revision
                      explorationId: 0199d001-7a8b-7c9d-8e0f-1a2b3c4d5e6f
                    - eventId: 0199e3c5-8a1c-7d2e-8f30-1b2c3d4e5f60
                      type: entity.bom.changed
                      occurredAt: '2026-10-20T18:04:13.002Z'
                      entityId: 0198aa10-4d5e-7f60-9b7c-8d9e0f1a2b3c
                      integrationId: 0197ff02-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                      entityType: Part Revision
                      explorationId: 0199d001-7a8b-7c9d-8e0f-1a2b3c4d5e6f
              resyncRequired:
                summary: Resync after the exploration was edited
                value:
                  deliveryId: 0199e3d1-2b3c-7d4e-9f50-6a7b8c9d0e1f
                  timestamp: '2026-10-21T09:12:05.114Z'
                  source: none
                  subscriptionId: 0199e3c4-1d2e-7f3a-8b4c-5d6e7f8a9b0c
                  events:
                    - eventId: 0199e3d0-1a2b-7c3d-8e4f-5a6b7c8d9e0f
                      type: subscription.resync_required
                      occurredAt: '2026-10-21T09:12:03.000Z'
                      explorationId: 0199d001-7a8b-7c9d-8e0f-1a2b3c4d5e6f
                      reason: exploration_changed
              ping:
                summary: Test request
                value:
                  deliveryId: 0199e3e0-3c4d-7e5f-8061-7b8c9d0e1f2a
                  timestamp: '2026-10-21T10:00:00.000Z'
                  source: none
                  subscriptionId: 0199e3c4-1d2e-7f3a-8b4c-5d6e7f8a9b0c
                  events:
                    - eventId: 0199e3e0-3c4d-7e5f-8061-7b8c9d0e1f2b
                      type: subscription.ping
                      occurredAt: '2026-10-21T10:00:00.000Z'
      responses:
        '2XX':
          description: Delivered. The response body is ignored.
        '408':
          description: Retried with backoff (1, 2, 4, 8, 16, 32, 60 minutes, then hourly).
        '429':
          description: Retried with backoff.
        '5XX':
          description: Retried with backoff. Timeouts and network errors are retried the same way.
        default:
          description: |
            Any other 4xx, or a 3xx (redirects are not followed), is a
            permanent failure; three in a row disable the webhook. A webhook
            with no 2xx for 6 hours is also disabled. Nothing is dropped: an
            admin's re-enable sends the backlog in order.
components:
  securitySchemes:
    violetSignature:
      type: apiKey
      in: header
      name: Violet-Signature
      description: |
        HMAC-SHA256 signature of `<t>.<raw body>`, keyed with the webhook's
        signing secret. See the `Violet-Signature` header parameter.
  schemas:
    WebhookRequest:
      type: object
      additionalProperties: false
      required: [deliveryId, timestamp, source, subscriptionId, events]
      properties:
        deliveryId:
          type: string
          format: uuid
          description: Identifies this request. Same as the `Violet-Delivery-Id` header and unchanged on retries.
        timestamp:
          type: string
          format: date-time
          description: When the batch was formed. Unchanged on retries.
        source:
          type: string
          pattern: '^[a-z0-9]+(-[a-z0-9]+)*$'
          description: |
            The system every event in this request comes from, as a lowercase
            slug. Connectors of one product share one slug (`teamcenter`,
            `altium`, `solidworks-pdm`); other apps use the slug of their name.
            `none` for pings and resync events.
          examples: [teamcenter, altium, solidworks-pdm, duro-hub, none]
        subscriptionId:
          type: string
          format: uuid
          description: The webhook's id.
        events:
          type: array
          minItems: 1
          maxItems: 500
          items:
            $ref: '#/components/schemas/Event'
    Event:
      oneOf:
        - $ref: '#/components/schemas/EntityEvent'
        - $ref: '#/components/schemas/ResyncRequiredEvent'
        - $ref: '#/components/schemas/PingEvent'
      discriminator:
        propertyName: type
        mapping:
          entity.created: '#/components/schemas/EntityEvent'
          entity.updated: '#/components/schemas/EntityEvent'
          entity.deleted: '#/components/schemas/EntityEvent'
          entity.bom.changed: '#/components/schemas/EntityEvent'
          entity.where_used.changed: '#/components/schemas/EntityEvent'
          entity.filter_entered: '#/components/schemas/EntityEvent'
          entity.filter_exited: '#/components/schemas/EntityEvent'
          subscription.resync_required: '#/components/schemas/ResyncRequiredEvent'
          subscription.ping: '#/components/schemas/PingEvent'
    EventBase:
      type: object
      required: [eventId, type, occurredAt]
      properties:
        eventId:
          type: string
          format: uuid
          description: Unique per event and kept on retries and redeliveries. Use it to deduplicate.
        occurredAt:
          type: string
          format: date-time
          description: When the change happened in Violet.
        explorationId:
          type: string
          format: uuid
          description: Present only on webhooks linked to an exploration.
    EntityEvent:
      allOf:
        - $ref: '#/components/schemas/EventBase'
        - type: object
          required: [entityId, integrationId, entityType]
          properties:
            type:
              type: string
              enum:
                - entity.created
                - entity.updated
                - entity.deleted
                - entity.bom.changed
                - entity.where_used.changed
                - entity.filter_entered
                - entity.filter_exited
              description: |
                - `entity.created`: a new entity of a watched type.
                - `entity.updated`: a watched property changed.
                - `entity.deleted`: the entity was deleted (linked webhooks: only entities they told you about).
                - `entity.bom.changed`: a line was added to or removed from the entity's own BOM, or a quantity changed.
                - `entity.where_used.changed`: the entity was added to or removed from a parent's BOM.
                - `entity.filter_entered`: linked only; the entity's own change made it match the exploration.
                - `entity.filter_exited`: linked only; the entity's own change made it stop matching.
            entityId:
              type: string
              format: uuid
              description: The changed entity. Read it with the Entities API.
            integrationId:
              type: string
              format: uuid
              description: The integration the entity belongs to.
            entityType:
              type: string
              description: The entity type name.
              examples: [Part Revision, Part]
    ResyncRequiredEvent:
      allOf:
        - $ref: '#/components/schemas/EventBase'
        - type: object
          required: [reason]
          properties:
            type:
              type: string
              const: subscription.resync_required
              description: Re-read everything the webhook watches.
            reason:
              type: string
              enum: [exploration_changed, capture_overflow, pending_purged, full_refetch]
              description: |
                - `exploration_changed`: the linked exploration's filters were edited.
                - `capture_overflow`: too many changes built up while the webhook was paused or disabled.
                - `pending_purged`: captured changes that had not been sent were cleared.
                - `full_refetch`: a source system was re-read in full.
            since:
              type: string
              format: date-time
              description: When known, re-read everything changed since this time.
    PingEvent:
      allOf:
        - $ref: '#/components/schemas/EventBase'
        - type: object
          properties:
            type:
              type: string
              const: subscription.ping
              description: A test sent from the app or the API.
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.violetlabs.com/features/api/outbound-webhooks/openapi-spec.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
