asyncapi: 2.6.0 info: title: Basecamp Webhook Events description: >- The Basecamp webhook system delivers real-time HTTP notifications to registered HTTPS endpoints when events occur within a Basecamp project. Webhooks are configured per project with a payload URL and an optional list of resource types. Basecamp sends an HTTP POST with a JSON payload to the registered URL whenever a subscribed event occurs. Delivery is attempted up to 10 times with exponential backoff before a webhook is deactivated if the endpoint fails to return a 2xx HTTP response. version: '1.0' contact: name: Basecamp Developer Support url: https://github.com/basecamp/bc3-api/blob/master/sections/webhooks.md termsOfService: https://basecamp.com/terms externalDocs: description: Basecamp Webhooks Documentation url: https://github.com/basecamp/bc3-api/blob/master/sections/webhooks.md servers: basecamp: url: 'https://3.basecampapi.com' protocol: https description: >- Basecamp sends webhook event notifications as HTTP POST requests originating from Basecamp infrastructure. Receiving endpoints must be publicly accessible HTTPS URLs registered via the Webhooks REST API. security: - bearerAuth: [] channels: /webhook: description: >- The HTTPS endpoint on the subscriber's server that receives webhook notifications from Basecamp. Basecamp sends HTTP POST requests with JSON payloads. Subscribers should respond with a 2xx status code within a reasonable timeout to acknowledge receipt. Failure to respond with 2xx after 10 attempts will cause Basecamp to deactivate the webhook. publish: operationId: receiveBasecampWebhook summary: Receive a Basecamp webhook event notification description: >- Basecamp sends this message to the subscriber's registered payload URL whenever a subscribed resource event occurs within a project. The payload includes the event kind, the recording object, the creator, and any event-specific details. message: oneOf: - $ref: '#/components/messages/MessageCreated' - $ref: '#/components/messages/MessageUpdated' - $ref: '#/components/messages/MessageArchived' - $ref: '#/components/messages/MessageTrashed' - $ref: '#/components/messages/TodoCreated' - $ref: '#/components/messages/TodoUpdated' - $ref: '#/components/messages/TodoCompleted' - $ref: '#/components/messages/TodoUncompleted' - $ref: '#/components/messages/TodoArchived' - $ref: '#/components/messages/TodoTrashed' - $ref: '#/components/messages/TodolistCreated' - $ref: '#/components/messages/TodolistUpdated' - $ref: '#/components/messages/TodolistArchived' - $ref: '#/components/messages/TodolistTrashed' - $ref: '#/components/messages/DocumentCreated' - $ref: '#/components/messages/DocumentUpdated' - $ref: '#/components/messages/DocumentArchived' - $ref: '#/components/messages/DocumentTrashed' - $ref: '#/components/messages/CommentCreated' - $ref: '#/components/messages/CommentUpdated' - $ref: '#/components/messages/CommentTrashed' - $ref: '#/components/messages/CardCreated' - $ref: '#/components/messages/CardUpdated' - $ref: '#/components/messages/CardArchived' - $ref: '#/components/messages/CardTrashed' - $ref: '#/components/messages/ScheduleEntryCreated' - $ref: '#/components/messages/ScheduleEntryUpdated' - $ref: '#/components/messages/ScheduleEntryArchived' - $ref: '#/components/messages/ScheduleEntryTrashed' - $ref: '#/components/messages/UploadCreated' - $ref: '#/components/messages/UploadUpdated' - $ref: '#/components/messages/UploadArchived' - $ref: '#/components/messages/UploadTrashed' - $ref: '#/components/messages/QuestionAnswerCreated' - $ref: '#/components/messages/QuestionAnswerUpdated' - $ref: '#/components/messages/QuestionPaused' - $ref: '#/components/messages/QuestionResumed' components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer token used to authenticate REST API calls to configure webhooks. Not used in the webhook delivery itself — delivery authentication relies on verifying the source IP or using shared secrets in the payload URL. messages: MessageCreated: name: message_created title: Message Created summary: A new message was created on a message board payload: $ref: '#/components/schemas/WebhookPayload' examples: - name: MessageCreatedExample payload: id: 9007199254741234 kind: message_created created_at: '2024-01-15T10:00:00.000Z' recording: id: 1234567 type: Message status: active title: Project Kickoff creator: id: 99 name: Alice Smith details: {} MessageUpdated: name: message_updated title: Message Updated summary: An existing message was updated payload: $ref: '#/components/schemas/WebhookPayload' MessageArchived: name: message_archived title: Message Archived summary: A message was archived payload: $ref: '#/components/schemas/WebhookPayload' MessageTrashed: name: message_trashed title: Message Trashed summary: A message was moved to trash payload: $ref: '#/components/schemas/WebhookPayload' TodoCreated: name: todo_created title: To-Do Created summary: A new to-do was created payload: $ref: '#/components/schemas/WebhookPayload' TodoUpdated: name: todo_updated title: To-Do Updated summary: An existing to-do was updated payload: $ref: '#/components/schemas/WebhookPayload' TodoCompleted: name: todo_completed title: To-Do Completed summary: A to-do was marked as completed payload: $ref: '#/components/schemas/WebhookPayload' TodoUncompleted: name: todo_uncompleted title: To-Do Uncompleted summary: A to-do was marked as incomplete payload: $ref: '#/components/schemas/WebhookPayload' TodoArchived: name: todo_archived title: To-Do Archived summary: A to-do was archived payload: $ref: '#/components/schemas/WebhookPayload' TodoTrashed: name: todo_trashed title: To-Do Trashed summary: A to-do was moved to trash payload: $ref: '#/components/schemas/WebhookPayload' TodolistCreated: name: todolist_created title: To-Do List Created summary: A new to-do list was created payload: $ref: '#/components/schemas/WebhookPayload' TodolistUpdated: name: todolist_updated title: To-Do List Updated summary: An existing to-do list was updated payload: $ref: '#/components/schemas/WebhookPayload' TodolistArchived: name: todolist_archived title: To-Do List Archived summary: A to-do list was archived payload: $ref: '#/components/schemas/WebhookPayload' TodolistTrashed: name: todolist_trashed title: To-Do List Trashed summary: A to-do list was moved to trash payload: $ref: '#/components/schemas/WebhookPayload' DocumentCreated: name: document_created title: Document Created summary: A new document was created in a vault payload: $ref: '#/components/schemas/WebhookPayload' DocumentUpdated: name: document_updated title: Document Updated summary: An existing document was updated payload: $ref: '#/components/schemas/WebhookPayload' DocumentArchived: name: document_archived title: Document Archived summary: A document was archived payload: $ref: '#/components/schemas/WebhookPayload' DocumentTrashed: name: document_trashed title: Document Trashed summary: A document was moved to trash payload: $ref: '#/components/schemas/WebhookPayload' CommentCreated: name: comment_created title: Comment Created summary: A new comment was posted on a recording payload: $ref: '#/components/schemas/WebhookPayload' CommentUpdated: name: comment_updated title: Comment Updated summary: An existing comment was updated payload: $ref: '#/components/schemas/WebhookPayload' CommentTrashed: name: comment_trashed title: Comment Trashed summary: A comment was moved to trash payload: $ref: '#/components/schemas/WebhookPayload' CardCreated: name: card_created title: Card Created summary: A new card was created on a card table payload: $ref: '#/components/schemas/WebhookPayload' CardUpdated: name: card_updated title: Card Updated summary: An existing card was updated or moved payload: $ref: '#/components/schemas/WebhookPayload' CardArchived: name: card_archived title: Card Archived summary: A card was archived payload: $ref: '#/components/schemas/WebhookPayload' CardTrashed: name: card_trashed title: Card Trashed summary: A card was moved to trash payload: $ref: '#/components/schemas/WebhookPayload' ScheduleEntryCreated: name: schedule_entry_created title: Schedule Entry Created summary: A new schedule entry was created payload: $ref: '#/components/schemas/WebhookPayload' ScheduleEntryUpdated: name: schedule_entry_updated title: Schedule Entry Updated summary: An existing schedule entry was updated payload: $ref: '#/components/schemas/WebhookPayload' ScheduleEntryArchived: name: schedule_entry_archived title: Schedule Entry Archived summary: A schedule entry was archived payload: $ref: '#/components/schemas/WebhookPayload' ScheduleEntryTrashed: name: schedule_entry_trashed title: Schedule Entry Trashed summary: A schedule entry was moved to trash payload: $ref: '#/components/schemas/WebhookPayload' UploadCreated: name: upload_created title: Upload Created summary: A new file upload was created in a vault payload: $ref: '#/components/schemas/WebhookPayload' UploadUpdated: name: upload_updated title: Upload Updated summary: An existing upload was updated payload: $ref: '#/components/schemas/WebhookPayload' UploadArchived: name: upload_archived title: Upload Archived summary: An upload was archived payload: $ref: '#/components/schemas/WebhookPayload' UploadTrashed: name: upload_trashed title: Upload Trashed summary: An upload was moved to trash payload: $ref: '#/components/schemas/WebhookPayload' QuestionAnswerCreated: name: question_answer_created title: Question Answer Created summary: A new answer was submitted to an automatic check-in question payload: $ref: '#/components/schemas/WebhookPayload' QuestionAnswerUpdated: name: question_answer_updated title: Question Answer Updated summary: An answer to an automatic check-in question was updated payload: $ref: '#/components/schemas/WebhookPayload' QuestionPaused: name: question_paused title: Question Paused summary: An automatic check-in question was paused payload: $ref: '#/components/schemas/WebhookPayload' QuestionResumed: name: question_resumed title: Question Resumed summary: A paused automatic check-in question was resumed payload: $ref: '#/components/schemas/WebhookPayload' schemas: WebhookPayload: type: object required: [id, kind, created_at, recording, creator] description: >- Standard JSON payload delivered by Basecamp to the registered webhook endpoint for all event types. The recording field contains the full representation of the resource that triggered the event. properties: id: type: integer description: Unique identifier for this webhook event kind: type: string description: >- Event type descriptor in the format {resource}_{action}, such as message_created, todo_completed, or document_updated. examples: - message_created - todo_completed - comment_created - card_updated created_at: type: string format: date-time description: ISO 8601 timestamp when the event occurred recording: $ref: '#/components/schemas/RecordingPayload' creator: $ref: '#/components/schemas/PersonPayload' details: type: object description: >- Event-specific metadata. For copy and move events this includes a copy object referencing the duplicated item. Contents vary by event kind. additionalProperties: true RecordingPayload: type: object description: >- Full representation of the Basecamp resource that triggered the webhook event. The exact fields present depend on the resource type. properties: id: type: integer description: Recording ID status: type: string description: Recording status at the time of the event enum: [active, archived, trashed] visible_to_clients: type: boolean description: Whether the recording is visible to client users created_at: type: string format: date-time description: Timestamp when the recording was created updated_at: type: string format: date-time description: Timestamp when the recording was last updated title: type: string description: Title or summary of the recording inherits_status: type: boolean description: Whether the recording inherits status from a parent type: type: string description: Recording type (Message, Todo, Document, Comment, etc.) url: type: string format: uri description: API URL for this recording app_url: type: string format: uri description: Web URL for this recording bucket: $ref: '#/components/schemas/BucketPayload' creator: $ref: '#/components/schemas/PersonPayload' content: type: string description: HTML-formatted body content (for messages, documents, comments) completed: type: boolean description: Whether the to-do is completed (for Todo type) due_on: type: string format: date description: Due date for to-dos and schedule entries nullable: true starts_at: type: string format: date-time description: Start time for schedule entries ends_at: type: string format: date-time description: End time for schedule entries assignees: type: array description: Assigned people (for Todos) items: $ref: '#/components/schemas/PersonPayload' BucketPayload: type: object description: Reference to the Basecamp project containing the recording properties: id: type: integer description: Project ID name: type: string description: Project name type: type: string description: Always "Project" PersonPayload: type: object description: Reference to the Basecamp user who created or triggered the event properties: id: type: integer description: Person ID attachable_sgid: type: string description: Signed global ID name: type: string description: Full name email_address: type: string format: email description: Email address personable_type: type: string description: Type of personable (User, Client) title: type: string description: Job title avatar_url: type: string format: uri description: URL to avatar image created_at: type: string format: date-time description: Account creation timestamp updated_at: type: string format: date-time description: Last update timestamp admin: type: boolean description: Whether the person is an account administrator time_zone: type: string description: IANA time zone name