Hustle Webhooks API

openapi: 3.1.0
info:
  title: Hustle Public Access Token Webhooks API
  version: v3
  description: The Hustle Public API exposes a RESTful interface to provide programmatic access to resources within your Hustle account. The API is defined using the OpenAPI specification (aka Swagger) which can be downloaded above and used to generate a client in various languages. This may help speed up integration with the API, but is not required.
servers:
- url: /v3
tags:
- name: Webhooks
paths:
  /webhook_registrations:
    get:
      summary: Get Webhook Registrations
      description: Get a list of webhook registrations scoped by the query parameters.
      tags:
      - Webhooks
      parameters:
      - schema:
          type: string
          description: Webhook registration ID.
        required: false
        description: Webhook registration ID.
        name: id
        in: query
      - schema:
          type: string
          enum:
          - consentUpdate-v1
          - messageStatus-v1
          description: Filter by webhook configuration type.
        required: false
        description: Filter by webhook configuration type.
        name: configType
        in: query
      - schema:
          type: string
          description: Cursor for start of next set of items. Pass whatever you receive from the response to get the next elements in the array.
        required: false
        description: Cursor for start of next set of items. Pass whatever you receive from the response to get the next elements in the array.
        name: cursor
        in: query
      - schema:
          type: number
          maximum: 1000
          minimum: 1
          description: Limit of items per page.
        required: false
        description: Limit of items per page.
        name: limit
        in: query
      responses:
        '200':
          description: Returns a list of webhook registrations that match the query parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookRegistration'
                    description: List of webhook registrations that match the specified filter.
                  cursor:
                    type:
                    - string
                    - 'null'
                    description: Cursor for start of next set of items. If there were no items to return with the last cursor you passed, this will return null.
                  hasMore:
                    type: boolean
                    description: Whether there are more items to load past this cursor.
                required:
                - items
                - cursor
                - hasMore
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Create Webhook Registration
      description: Create a new webhook registration to receive webhook events. For more information and documentation, see https://api.hustle.com/docs/webhooks.
      tags:
      - Webhooks
      requestBody:
        description: The details of the webhook registration being created.
        content:
          application/json:
            schema:
              type: object
              properties:
                targetUrl:
                  type: string
                  format: uri
                  description: The URL that will receive webhook events.
                secretForHMAC:
                  type: string
                  description: Secret key used for HMAC signature verification of webhook events.
                config:
                  $ref: '#/components/schemas/WebhookConfig'
              required:
              - targetUrl
              - secretForHMAC
              - config
              additionalProperties: false
      responses:
        '201':
          description: Returns the created webhook registration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRegistration'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /webhook_registrations/{id}:
    put:
      summary: Update Webhook Registration
      description: Update an existing webhook registration.
      tags:
      - Webhooks
      parameters:
      - schema:
          type: string
          description: The ID of the webhook registration to update.
        required: true
        description: The ID of the webhook registration to update.
        name: id
        in: path
      requestBody:
        description: The details of the webhook registration to update.
        content:
          application/json:
            schema:
              type: object
              properties:
                targetUrl:
                  type: string
                  format: uri
                  description: The URL that will receive webhook events.
                secretForHMAC:
                  type: string
                  description: Secret key used for HMAC signature verification of webhook events.
                config:
                  $ref: '#/components/schemas/WebhookConfig'
              additionalProperties: false
      responses:
        '200':
          description: Returns the updated webhook registration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRegistration'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete Webhook Registration
      description: Delete an existing webhook registration.
      tags:
      - Webhooks
      parameters:
      - schema:
          type: string
          description: The ID of the webhook registration to delete.
        required: true
        description: The ID of the webhook registration to delete.
        name: id
        in: path
      responses:
        '200':
          description: Returns confirmation of successful deletion.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the deletion was successful.
                required:
                - success
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /webhook_registrations/mock_event:
    post:
      '400':
        description: Bad Request
        content:
          application/json:
            schema:
              ~standard:
                vendor: zod
                version: 1
              def:
                type: object
                shape:
                  code:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: number
                      checks: []
                    minValue: null
                    maxValue: null
                    isInt: false
                    isFinite: true
                    format: null
                  message:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: string
                    format: null
                    minLength: null
                    maxLength: null
                  hustleErrorCode:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: optional
                      innerType:
                        ~standard:
                          vendor: zod
                          version: 1
                        def:
                          type: string
                        format: null
                        minLength: null
                        maxLength: null
                catchall:
                  ~standard:
                    vendor: zod
                    version: 1
                  def:
                    type: never
      '401':
        description: Unauthorized
        content:
          application/json:
            schema:
              ~standard:
                vendor: zod
                version: 1
              def:
                type: object
                shape:
                  code:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: number
                      checks: []
                    minValue: null
                    maxValue: null
                    isInt: false
                    isFinite: true
                    format: null
                  message:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: string
                    format: null
                    minLength: null
                    maxLength: null
                  hustleErrorCode:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: optional
                      innerType:
                        ~standard:
                          vendor: zod
                          version: 1
                        def:
                          type: string
                        format: null
                        minLength: null
                        maxLength: null
                catchall:
                  ~standard:
                    vendor: zod
                    version: 1
                  def:
                    type: never
      '404':
        description: Not Found
        content:
          application/json:
            schema:
              ~standard:
                vendor: zod
                version: 1
              def:
                type: object
                shape:
                  code:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: number
                      checks: []
                    minValue: null
                    maxValue: null
                    isInt: false
                    isFinite: true
                    format: null
                  message:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: string
                    format: null
                    minLength: null
                    maxLength: null
                  hustleErrorCode:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: optional
                      innerType:
                        ~standard:
                          vendor: zod
                          version: 1
                        def:
                          type: string
                        format: null
                        minLength: null
                        maxLength: null
                catchall:
                  ~standard:
                    vendor: zod
                    version: 1
                  def:
                    type: never
      '422':
        description: Unprocessable Entity
        content:
          application/json:
            schema:
              ~standard:
                vendor: zod
                version: 1
              def:
                type: object
                shape:
                  code:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: number
                      checks: []
                    minValue: null
                    maxValue: null
                    isInt: false
                    isFinite: true
                    format: null
                  message:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: string
                    format: null
                    minLength: null
                    maxLength: null
                  hustleErrorCode:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: optional
                      innerType:
                        ~standard:
                          vendor: zod
                          version: 1
                        def:
                          type: string
                        format: null
                        minLength: null
                        maxLength: null
                catchall:
                  ~standard:
                    vendor: zod
                    version: 1
                  def:
                    type: never
      '500':
        description: Internal Server Error
        content:
          application/json:
            schema:
              ~standard:
                vendor: zod
                version: 1
              def:
                type: object
                shape:
                  code:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: number
                      checks: []
                    minValue: null
                    maxValue: null
                    isInt: false
                    isFinite: true
                    format: null
                  message:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: string
                    format: null
                    minLength: null
                    maxLength: null
                  hustleErrorCode:
                    ~standard:
                      vendor: zod
                      version: 1
                    def:
                      type: optional
                      innerType:
                        ~standard:
                          vendor: zod
                          version: 1
                        def:
                          type: string
                        format: null
                        minLength: null
                        maxLength: null
                catchall:
                  ~standard:
                    vendor: zod
                    version: 1
                  def:
                    type: never
      summary: Mock Webhook Event
      description: Mock a webhook event.
      tags:
      - Webhooks
      requestBody:
        description: The details of the webhook event to mock.
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                    - webhookRegistrationId
                    description: Mock an event for a specific webhook registration that already exists.
                  webhookRegistrationId:
                    type: string
                    description: The ID of the webhook registration to mock an event for.
                required:
                - type
                additionalProperties: false
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                    - mockWebhookRegistration
                    description: Mock an event for a new webhook registration.
                  targetUrl:
                    type: string
                    format: uri
                    description: The URL that will receive webhook events.
                  secretForHMAC:
                    type: string
                    description: Secret key used for HMAC signature verification of webhook events.
                  config:
                    allOf:
                    - $ref: '#/components/schemas/WebhookConfig'
                    - description: The webhook configuration to mock an event for.
                required:
                - type
                - targetUrl
                - config
                additionalProperties: false
      responses:
        '200':
          description: Returns the mocked webhook event.
          content:
            application/json:
              schema:
                type: object
                properties:
                  willPassValidation:
                    type: boolean
                    description: Whether the mock webhook event passed ownership validation when sent to the target URL.
                  accountId:
                    type: string
                    description: The account ID that the current logged in key belongs to. Put here for convenience so you know what to return in the "hustle-webhook-confirmation" header.
                required:
                - willPassValidation
                - accountId
                additionalProperties: false
components:
  schemas:
    WebhookAccountScopeV1:
      type: object
      properties:
        type:
          type: string
          enum:
          - account
          description: Scope the webhook to leads in the entire account.
      required:
      - type
      additionalProperties: false
    MessageStatusV1Config:
      type: object
      properties:
        type:
          type: string
          enum:
          - messageStatus-v1
          description: Message Status updates are sent when a message status changes (e.g., delivered, failed).
        scope:
          oneOf:
          - $ref: '#/components/schemas/WebhookOrganizationsScopeV1'
          - $ref: '#/components/schemas/WebhookAccountScopeV1'
          discriminator:
            propertyName: type
            mapping:
              organizations: '#/components/schemas/WebhookOrganizationsScopeV1'
              account: '#/components/schemas/WebhookAccountScopeV1'
      required:
      - type
      - scope
      additionalProperties: false
    WebhookRegistration:
      type: object
      properties:
        id:
          type: string
          description: The ID of the webhook registration.
        type:
          type: string
          enum:
          - webhook_registration
          description: The type of object the attached ID corresponds to.
        targetUrl:
          type: string
          format: uri
          description: The URL that will receive webhook events.
        config:
          $ref: '#/components/schemas/WebhookConfig'
        createdAt:
          type: string
          description: An ISO-8601 string representing the date the webhook registration was created.
        secretForHMAC:
          type: boolean
          description: Whether a secret is currently active for HMAC signature verification of webhook events. We do not ever return the secret so if you have lost your copy, you will need to set a new one.
      required:
      - id
      - type
      - targetUrl
      - config
      - createdAt
      - secretForHMAC
      additionalProperties: false
      description: A webhook registration defines when and where webhook events should be sent.
    WebhookConfig:
      oneOf:
      - $ref: '#/components/schemas/ConsentUpdateV1Config'
      - $ref: '#/components/schemas/MessageStatusV1Config'
      discriminator:
        propertyName: type
        mapping:
          consentUpdate-v1: '#/components/schemas/ConsentUpdateV1Config'
          messageStatus-v1: '#/components/schemas/MessageStatusV1Config'
      description: The configuration object for the webhook.
    WebhookOrganizationsScopeV1:
      type: object
      properties:
        type:
          type: string
          enum:
          - organizations
          description: Scope the webhook to leads in specific organizations.
        organizationIds:
          type: array
          items:
            type: string
          description: Array of organization IDs to scope the webhook to.
      required:
      - type
      - organizationIds
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        code:
          type: number
          description: Error code; usually the status code.
        message:
          type: string
          description: Error message detailing the error.
        hustleErrorCode:
          type: string
          description: Sometimes available (generally with 422 responses). If the message is not descriptive enough to help identify the issue, pass this code to Hustle support.
      required:
      - code
      - message
      additionalProperties: false
    ConsentUpdateV1Config:
      type: object
      properties:
        type:
          type: string
          enum:
          - consentUpdate-v1
          description: Consent Updates are sent when a lead updates their consent status to opt-in or opt-out of communications.
        scope:
          oneOf:
          - $ref: '#/components/schemas/WebhookOrganizationsScopeV1'
          - $ref: '#/components/schemas/WebhookAccountScopeV1'
          discriminator:
            propertyName: type
            mapping:
              organizations: '#/components/schemas/WebhookOrganizationsScopeV1'
              account: '#/components/schemas/WebhookAccountScopeV1'
        includeOptOut:
          type: boolean
          description: Whether to include opt-out events in the webhook.
        includeOptIn:
          type: boolean
          description: Whether to include opt-in events in the webhook.
      required:
      - type
      - scope
      - includeOptOut
      - includeOptIn
      additionalProperties: false
externalDocs:
  description: Click here for a more in-depth user guide or links to prior versions of the api documentation.
  url: description.html