Asana Webhooks Events API

asyncapi: 2.6.0
info:
  title: Asana Webhooks Events API
  version: '1.0'
  description: >-
    The Asana Webhooks Events API delivers real-time event notifications to
    your application when changes occur on Asana resources. Webhooks use HTTP
    POST to deliver events to a target URL you configure. Events are delivered
    within a minute on average using an at-most-once delivery system.

    Establishing a webhook requires a two-part handshake process. When a webhook
    is created, Asana sends a test POST to the target URL with an X-Hook-Secret
    header. The target must respond with a 200 OK or 204 No Content and echo
    back the X-Hook-Secret header to confirm the subscription.

    Subsequent event deliveries include an X-Hook-Signature header containing
    an HMAC-SHA256 signature of the request body using the X-Hook-Secret as the
    key, which can be used to verify event authenticity.
  termsOfService: https://asana.com/terms
  contact:
    name: Asana Support
    url: https://asana.com/support
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

servers:
  production:
    url: https://app.asana.com/api/1.0
    protocol: http
    description: >-
      Asana sends webhook events via HTTP POST to your configured target URL.
      You configure the target URL when establishing a webhook via the REST API.

channels:
  /webhooks/events:
    description: >-
      Channel for receiving Asana webhook events. Events are delivered as HTTP
      POST requests to the target URL configured when the webhook was created.
      Events bubble up from child resources (e.g., subscribing to a project
      will include events for tasks within that project).
    subscribe:
      operationId: receiveWebhookEvents
      summary: Receive webhook events
      description: >-
        Receive real-time event notifications when changes occur on Asana
        resources that match the webhook's subscription and filters.
      message:
        oneOf:
          - $ref: '#/components/messages/WebhookEvent'
          - $ref: '#/components/messages/WebhookHandshake'

components:
  messages:
    WebhookHandshake:
      name: WebhookHandshake
      title: Webhook Confirmation Handshake
      summary: >-
        Initial handshake request sent by Asana when a webhook is created.
        The target must respond with a 200 OK and echo back the X-Hook-Secret.
      headers:
        type: object
        properties:
          X-Hook-Secret:
            type: string
            description: >-
              A secret token that must be echoed back in the response header to
              confirm the webhook subscription. Store this secret to verify
              future event signatures.
            example: b537207f20cbfa02357cf448134da559e8bd39d61597dcd5631b8012eae53e81
      payload:
        type: object
        description: The handshake request has an empty body.

    WebhookEvent:
      name: WebhookEvent
      title: Webhook Event Delivery
      summary: >-
        An event delivery containing one or more change events on Asana resources.
      headers:
        type: object
        properties:
          X-Hook-Signature:
            type: string
            description: >-
              HMAC-SHA256 signature of the request body using the X-Hook-Secret
              as the key. Use this to verify the authenticity of the event.
            example: 4f537f6c83ee5425767b5b8f291a2c0df8b79ece6fca3440b42cf2d63fe58580
      payload:
        $ref: '#/components/schemas/WebhookEventPayload'

  schemas:
    WebhookEventPayload:
      type: object
      description: The payload delivered to the webhook target URL.
      properties:
        events:
          type: array
          description: Array of event objects representing changes to resources.
          items:
            $ref: '#/components/schemas/Event'

    Event:
      type: object
      description: >-
        An event representing a change to a resource observed by a webhook.
        Pay close attention to the relationship between Event.action and
        Event.change.action.
      properties:
        user:
          type: object
          nullable: true
          description: >-
            The user who triggered the event. May be null for system-generated events.
          properties:
            gid:
              type: string
              description: Globally unique identifier of the user.
              example: '12345'
            resource_type:
              type: string
              example: user
        resource:
          type: object
          description: The resource that was modified and triggered the event.
          properties:
            gid:
              type: string
              description: Globally unique identifier of the resource.
              example: '67890'
            resource_type:
              type: string
              description: The type of the resource (e.g., task, project, story).
              example: task
            resource_subtype:
              type: string
              description: The subtype of the resource.
              example: default_task
        type:
          type: string
          description: >-
            Deprecated. The type of resource that generated the event. Use
            resource.resource_type instead.
          example: task
        action:
          type: string
          description: >-
            The type of action taken on the resource. One of changed, added,
            removed, deleted, or undeleted.
          enum:
            - changed
            - added
            - removed
            - deleted
            - undeleted
          example: changed
        parent:
          type: object
          nullable: true
          description: >-
            For added/removed events, the parent object that the resource was
            added to or removed from. Null for other event types.
          properties:
            gid:
              type: string
              example: '11111'
            resource_type:
              type: string
              example: project
        created_at:
          type: string
          format: date-time
          description: The timestamp when the event occurred.
          example: '2024-01-15T10:30:00.000Z'
        change:
          type: object
          nullable: true
          description: >-
            Information about the field-level change. Only present when the
            event action is "changed".
          properties:
            field:
              type: string
              description: The name of the field that changed.
              example: assignee
            action:
              type: string
              description: >-
                The type of action on the field. One of changed, added, or removed.
              enum:
                - changed
                - added
                - removed
              example: changed
            new_value:
              type: object
              nullable: true
              description: >-
                Present when change.action is "changed" and the new value is an
                Asana resource. Contains only gid and resource_type from webhooks.
              properties:
                gid:
                  type: string
                resource_type:
                  type: string
            added_value:
              type: object
              nullable: true
              description: >-
                Present when change.action is "added" and the added value is an
                Asana resource.
              properties:
                gid:
                  type: string
                resource_type:
                  type: string
            removed_value:
              type: object
              nullable: true
              description: >-
                Present when change.action is "removed" and the removed value is
                an Asana resource.
              properties:
                gid:
                  type: string
                resource_type:
                  type: string