SpotDraft V2.1 Webhooks API

openapi: 3.2.0
info:
  title: SpotDraft V2.1 Webhooks API
  version: v1
  x-version: v1
  x-logo:
    url: https://cdn.spotdraft.com/assets/logo-black-new.png
    backgroundColor: transparent
    altText: SpotDraft Logo
    href: https://spotdraft.com
  x-favicon: https://cdn.spotdraft.com/assets/favicon.png
  x-footer: © SpotDraft Inc. All rights reserved.
  description: '# SpotDraft Public API


    Welcome to the **SpotDraft Public API**.'
servers:
- url: https://api.eu.spotdraft.com
  description: Europe
- url: https://api.in.spotdraft.com
  description: India
- url: https://api.us.spotdraft.com
  description: United States
- url: https://api.me.spotdraft.com
  description: Middle East
tags:
- name: V2.1 Webhooks
  description: Create webhook subscriptions, inspect sample payloads, validate deliveries, and manage webhook secrets across public API versions.
paths:
  /api/v2.1/public/webhooks/:
    post:
      operationId: v2.1_public_webhooks_create
      description: 'Creates a webhook subscription for the selected SpotDraft activity types.

        See Webhooks for delivery behavior, verification, and retry guidance.'
      summary: Setup Webhook
      tags:
      - V2.1 Webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicWebhookCreateRequest'
            examples:
              Example1:
                value:
                  title: Contract Created webhook
                  only_for_activities:
                  - CONTRACT_CREATED
                  url: https://yourdomain.com/webhooks/event-handler
                  description: Created for contract create webhook
                  custom_headers:
                    X-ABC-ACCESS-KEY: example-access-key
                    X-CLIENT-SIGNATURE: example-client-signature
                summary: Example 1
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PublicWebhookCreateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PublicWebhookCreateRequest'
        required: true
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicWebhookResponse'
              examples:
                Example1:
                  value:
                    id: 511
                    title: Contract Created webhook
                    only_for_activities:
                    - CONTRACT_CREATED
                    url: https://yourdomain.com/webhooks/event-handler
                    created_by_user:
                      id: 17258
                      name: Mike Reed
                      email: mike_reed@yahoo.com
                      designation: Senior Marketing Manager
                    description: Created for contract create webhook
                    custom_headers:
                      X-ABC-ACCESS-KEY: example-access-key
                      DEF-ACCESS-KEY: example-secondary-access-key
                    status: ACTIVE
                  summary: Example 1
          description: Created
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  status_code:
                    type: integer
                  code:
                    type: string
                  message:
                    type: string
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  status_code:
                    type: integer
                  code:
                    type: string
                  message:
                    type: string
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  status_code:
                    type: integer
                  code:
                    type: string
                  message:
                    type: string
          description: Not Found
      x-tagGroup: Platform
  /api/v2.1/public/webhooks/hmac_key/:
    get:
      operationId: v2.1_public_webhooks_hmac_key_get
      description: 'Returns the Base64-encoded HMAC secret used to verify webhook payload signatures.

        See Webhooks for verification guidance.'
      summary: Get Webhook Secret
      tags:
      - V2.1 Webhooks
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSecretKeyResponse'
              examples:
                Example1:
                  value:
                    hmac_key: zJDCvFUXhByUkPcQIzf+dt2W7bqm6x6Fb2o/gLhfUgXyPqvPcrZ6P9yYtoUrI4dErHzq2t+4gjZ4zH2btdpoSA==
                  summary: Example 1
          description: Success
      x-tagGroup: Platform
  /api/v2.1/public/webhooks/{webhook_id}:
    delete:
      operationId: v2.1_public_webhooks_destroy
      description: 'Deletes an existing webhook subscription.

        See Webhooks for delivery behavior and operational guidance.'
      summary: Remove Webhook
      parameters:
      - in: path
        name: webhook_id
        schema:
          type: integer
        required: true
      tags:
      - V2.1 Webhooks
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '204':
          description: Success
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  status_code:
                    type: integer
                  code:
                    type: string
                  message:
                    type: string
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  status_code:
                    type: integer
                  code:
                    type: string
                  message:
                    type: string
          description: Not Found
      x-tagGroup: Platform
components:
  schemas:
    PublicWebhookResponseStatusEnum:
      enum:
      - ACTIVE
      - DISABLED_BY_USER
      - DISABLED_BY_ERROR
      type: string
    OnlyForActivitiesEnum:
      enum:
      - CONTRACT_VERSION_UPLOADED
      - CONTRACT_APPROVAL_COMPLETED
      - CONTRACT_APPROVAL_REQUESTED
      - CONTRACT_CREATED
      - CONTRACT_DATA_UPDATED
      - CONTRACT_DELETED
      - CONTRACT_EXECUTED
      - CONTRACT_MARK_FOR_EXECUTION
      - CONTRACT_SENT_TO_COUNTERPARTY
      - CONTRACT_SIGNATURE_DECLINED
      - CONTRACT_SIGNATURE_REQUESTED
      - CONTRACT_SIGNED
      - CONTRACT_UNMARK_FOR_EXECUTION
      - POSTMARK_EMAIL_EVENT
      - CONTRACT_KEY_POINTER_UPDATION
      - CONTRACT_KEY_POINTER_CREATION
      - SIGNING_EMAIL_DELIVERED
      - SIGNING_EMAIL_OPENED
      - SIGNING_EMAIL_NOT_DELIVERED
      - SIGNING_EMAIL_LINK_CLICKED
      - REDLINING_EMAIL_DELIVERED
      - REDLINING_EMAIL_OPENED
      - REDLINING_EMAIL_NOT_DELIVERED
      - REDLINING_EMAIL_LINK_CLICKED
      - CONTRACT_SIGNATURE_REQUESTED_NOTIFICATION_SENT
      - COUNTER_PARTY_CREATED
      - COUNTER_PARTY_UPDATED
      - COUNTER_PARTY_CONTACT_CREATED
      - COUNTER_PARTY_CONTACT_UPDATED
      - COUNTER_PARTY_ADDRESS_CREATED
      - COUNTER_PARTY_ADDRESS_UPDATED
      - CONTRACT_ACTIVITY_LOG_COMMENT_CREATED
      - CONTRACT_VOIDED
      - CONTRACT_PROCESS_METRIC_UPDATED
      - CONTRACT_EXTERNAL_METADATA_CREATED
      - CONTRACT_EXTERNAL_METADATA_UPDATED
      - CONTRACT_ENTITY_UPDATED
      type: string
    PublicWebhookCreateRequest:
      title: PublicWebhookCreateRequest
      type: object
      properties:
        title:
          title: Title
          description: The title of this webhook
          minLength: 1
          type: string
        description:
          title: Description
          description: The description for the webhook
          type: string
        custom_headers:
          title: Custom Headers
          description: Custom headers to be included in the webhook call. Header names are trimmed before validation. Use custom header names only; standard HTTP headers are rejected. Header names should start with `X-` and must not start with X-Google-, X-Goog-, X-GFE-, X-Amz-, X-MS-, X-DD-, X-Datadog-, X-B3-, X-SD- and X-SPOTDRAFT-.
          type: object
        only_for_activities:
          description: Webhook activity types for which to trigger this webhook. The list cannot be empty.
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/OnlyForActivitiesEnum'
            title: ContractWebhookActivityType
            description: An enumeration.
        url:
          title: Url
          description: The HTTPS URL that should receive this event. Non-HTTPS URLs are rejected.
          minLength: 1
          type: string
      required:
      - title
      - only_for_activities
      - url
      examples:
      - title: Contract Created webhook
        only_for_activities:
        - CONTRACT_CREATED
        url: https://yourdomain.com/webhooks/event-handler
        description: Created for contract create webhook
        custom_headers:
          X-ABC-ACCESS-KEY: example-access-key
          X-CLIENT-SIGNATURE: example-client-signature
    PublicWebhookResponse:
      title: PublicWebhookResponse
      type: object
      properties:
        id:
          title: Id
          description: Webhook ID
          type: integer
        title:
          title: Title
          description: The title of this webhook
          minLength: 1
          type: string
        only_for_activities:
          description: Webhook activity types for which to trigger this webhook
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/OnlyForActivitiesEnum'
            title: ContractWebhookActivityType
            description: An enumeration.
        url:
          title: Url
          description: The url to receive this event
          type: string
        created_by_user:
          title: Created By User
          type: object
          properties:
            id:
              title: Id
              description: ID of the user
              type: integer
            email:
              title: Email
              description: Email Id of the user
              type: string
            name:
              title: Name
              description: Name of the user
              type: string
            designation:
              title: Designation
              description: Designation of the user within the organization
              type: string
          required:
          - id
          - email
          - name
          description: Basic details of the user who created the webhook
        description:
          title: Description
          description: The description for the webhook
          type: string
        custom_headers:
          title: Custom Headers
          description: Custom headers to be included in the webhook call
          type: object
        status:
          allOf:
          - $ref: '#/components/schemas/PublicWebhookResponseStatusEnum'
          title: ContractActivityWebhookStatus
          description: The status of the webhook
      required:
      - id
      - title
      - url
      - status
      examples:
      - id: 511
        title: Contract Created webhook
        only_for_activities:
        - CONTRACT_CREATED
        url: https://yourdomain.com/webhooks/event-handler
        created_by_user:
          id: 17258
          name: Mike Reed
          email: mike_reed@yahoo.com
          designation: Senior Marketing Manager
        description: Created for contract create webhook
        custom_headers:
          X-ABC-ACCESS-KEY: example-access-key
          DEF-ACCESS-KEY: example-secondary-access-key
        status: ACTIVE
    WebhookSecretKeyResponse:
      title: WebhookSecretKeyResponse
      type: object
      properties:
        hmac_key:
          title: Hmac Key
          description: Base64 of the secret for webhook
          minLength: 1
          type: string
      required:
      - hmac_key
      examples:
      - hmac_key: zJDCvFUXhByUkPcQIzf+dt2W7bqm6x6Fb2o/gLhfUgXyPqvPcrZ6P9yYtoUrI4dErHzq2t+4gjZ4zH2btdpoSA==
  securitySchemes:
    ClickwrapId:
      type: apiKey
      in: header
      name: clickwrap-id
      description: Public clickwrap identifier header.
    ClientId:
      type: apiKey
      name: client-id
      in: header
    ClientSecret:
      type: apiKey
      name: client-secret
      in: header
    NativeIntegrationBasic:
      type: http
      scheme: basic
      description: HTTP Basic auth for supported native integrations. Send base64(client_id:client_secret) in the Authorization header.
    OAuthBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token for workspace user access.
    Origin:
      type: apiKey
      in: header
      name: Origin
      description: Browser origin header used for clickwrap domain validation.
x-logo:
  url: https://cdn.spotdraft.com/assets/logo-black-new.png
  backgroundColor: transparent
  altText: SpotDraft Logo
  href: https://spotdraft.com
x-tagGroups:
- name: Contracts
  tags:
  - V2.1 Contract APIs
  - V2 Contract APIs
  - V1 Contract APIs
  - V2.1 Contract Approvals
  - V2 Contract Approvals
  - V2.1 Contract Activity
  - V2 Contract Activity
  - V2.1 Contract Invitations
  - V2 Contract Invitations
  - V2.1 Contract Metadata Values
  - V2 Contract Metadata Values
  - V2.1 Contract External Metadata
  - V2.1 Contract Notes
  - V2 Contract Notes
  - V2.1 Contract Obligations
  - V2.1 Contract Facets
  - V2.1 Contract Versions
  - V2 Contract Versions
  - V2.1 Recipients
  - V2 Recipients
- name: Clickwrap
  tags:
  - V2.1 Clickwrap
- name: Legal Intake
  tags:
  - V1 Legal Intake
- name: Workflow
  tags:
  - V2.1 Contract Metadata Definitions
  - V2 Contract Metadata Definitions
  - V2.1 Contract Types
  - V2 Contract Types
  - V2.1 Templates
  - V2 Templates
  - V1 Templates
- name: Platform
  tags:
  - V2.1 Users
  - V2 Users
  - V1 Users
  - V2.1 Counterparties
  - V2 Counterparties
  - V2.1 Organizations
  - V2 Organizations
  - V1 Obligation Types
  - V1 Native Integrations
  - V2.1 Workspace Files
  - V2.1 Tasks and Reminders
  - V2 Tasks and Reminders
  - V2.1 Webhooks
  - V1 Webhooks
  - V1 Emails
  - V2.1 Analytics Query
  - V2.1 Workspaces
  - V2.1 Workspace Tags
- name: Sidebar
  tags:
  - V2.1 Sidebar