---
updatedAt: 2026-06-30T13:39:21.000Z
agentTools:
  projectIndex: https://docs.bkbn.com/llms.txt
---

# Enable or disable webhook

Enables or disables the webhook for the authenticated client. When disabled, the webhook configuration is preserved but no webhook calls will be made. This is useful for temporarily stopping webhook notifications without losing the configuration.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "BKBN Sync API",
    "description": "API connector for customer applications.",
    "version": "2.16.0"
  },
  "servers": [
    {
      "url": "http://sync-dev.bkbn.com",
      "description": "Generated server url"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Webhooks",
      "description": "Operations for managing webhook configuration and trigger history"
    },
    {
      "name": "Webhook Events",
      "description": "Event payloads BKBN POSTs to your callback URL. You receive these; you do not call them."
    }
  ],
  "paths": {
    "/v1/webhooks": {
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Enable or disable webhook",
        "description": "Enables or disables the webhook for the authenticated client. When disabled, the webhook configuration is preserved but no webhook calls will be made. This is useful for temporarily stopping webhook notifications without losing the configuration.",
        "operationId": "setWebhookEnabled",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPatch"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Webhook status successfully updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Webhook"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {}
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {}
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {}
            }
          },
          "404": {
            "description": "Webhook not found",
            "content": {
              "application/json": {}
            }
          },
          "422": {
            "description": "Unprocessable entity",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Webhook": {
        "type": "object",
        "description": "Configuration for the callback endpoint that receives event notifications.",
        "required": [
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true,
            "description": "Unique identifier of the webhook.",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The URL where webhook events will be sent.",
            "example": "https://api.example.com/webhooks/events"
          },
          "method": {
            "$ref": "#/components/schemas/WebhookHttpMethod"
          },
          "enabled": {
            "type": "boolean",
            "default": true,
            "description": "Whether the webhook is enabled and will receive events.",
            "example": true
          },
          "authType": {
            "$ref": "#/components/schemas/WebhookAuthType"
          },
          "authSecret": {
            "type": "string",
            "writeOnly": true,
            "description": "Authentication secret/token. Write-only; never returned. Omit on update to keep the current value.",
            "example": "your-secret-token"
          },
          "hasAuthSecret": {
            "type": "boolean",
            "readOnly": true,
            "description": "Indicates whether an authentication secret is configured.",
            "example": true
          },
          "authHeaderName": {
            "type": "string",
            "description": "Header name to use when authType is HEADER (defaults to X-API-Key if omitted).",
            "example": "X-API-Key"
          },
          "authParameterName": {
            "type": "string",
            "description": "Query parameter name to use when authType is QUERY_PARAMETER.",
            "example": "api_key"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "example": "2023-12-01T10:30:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "example": "2023-12-01T15:45:00Z"
          },
          "lastTriggeredAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "example": "2023-12-01T16:20:00Z"
          }
        }
      },
      "WebhookPatch": {
        "type": "object",
        "description": "Request body for enabling/disabling the webhook.",
        "required": [
          "enabled"
        ],
        "properties": {
          "enabled": {
            "type": "boolean",
            "description": "Whether the webhook should be enabled.",
            "example": true
          }
        }
      },
      "WebhookAuthType": {
        "type": "string",
        "description": "Authentication BKBN applies when calling your endpoint. NONE = no auth; HEADER = custom header (authHeaderName, default X-API-Key) set to the secret; QUERY_PARAMETER = secret appended as query param (authParameterName); BEARER_TOKEN = `Authorization: Bearer {secret}`.\n",
        "default": "NONE",
        "enum": [
          "NONE",
          "HEADER",
          "QUERY_PARAMETER",
          "BEARER_TOKEN"
        ]
      },
      "WebhookHttpMethod": {
        "type": "string",
        "description": "HTTP method BKBN uses when calling your endpoint.",
        "default": "GET",
        "enum": [
          "GET",
          "POST"
        ]
      },
      "VisualsReadyEvent": {
        "type": "object",
        "required": [
          "event",
          "timestamp",
          "orderId",
          "assignmentId",
          "visualType",
          "product"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "VISUALS_READY"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When the webhook was sent.",
            "example": "2023-01-15T12:45:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "visualType": {
            "type": "string",
            "description": "Resource type that is ready. Mirrors the platform resource taxonomy.",
            "example": "POST"
          },
          "product": {
            "type": "string",
            "description": "Product/deliverable that is ready. Mirrors the platform product taxonomy.",
            "example": "GROUND_PHOTO"
          },
          "realEstatePropertyId": {
            "type": "string",
            "format": "uuid",
            "description": "Real estate property id, if applicable."
          },
          "objectReferenceId": {
            "type": "string",
            "description": "Client-supplied object reference, if provided."
          }
        }
      },
      "PhotographerBookedEvent": {
        "type": "object",
        "required": [
          "event",
          "timestamp",
          "orderId",
          "photographerId"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "PHOTOGRAPHER_BOOKED"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2023-01-15T12:45:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "photographerId": {
            "type": "string",
            "description": "Public id of the photographer (creative) who accepted.",
            "example": "55021"
          },
          "assignmentId": {
            "type": "string",
            "description": "Assignment id, when available.",
            "example": "a1b2c3d4"
          }
        }
      },
      "OrderStatusUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "previousStatus",
          "newStatus"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "ORDER_STATUS_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the change occurred on the platform.",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "previousStatus": {
            "type": "string",
            "example": "PLACED"
          },
          "newStatus": {
            "type": "string",
            "example": "IN_PROGRESS"
          }
        }
      },
      "AssignmentStatusUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "assignmentId",
          "previousStatus",
          "newStatus"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "ASSIGNMENT_STATUS_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "previousStatus": {
            "type": "string",
            "example": "SCHEDULED"
          },
          "newStatus": {
            "type": "string",
            "example": "IN_PRODUCTION"
          },
          "assignmentType": {
            "type": "string",
            "description": "Assignment type, when available."
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "description": "Confirmed shooting start, when available."
          },
          "estimatedDeliveryAt": {
            "type": "string",
            "format": "date",
            "description": "Estimated delivery date (date-only), when available."
          },
          "actionRequired": {
            "type": "string",
            "description": "Action-required detail, when applicable."
          }
        }
      },
      "AppointmentDateUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "assignmentId",
          "scheduledAt"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "APPOINTMENT_DATE_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "assignmentType": {
            "type": "string",
            "description": "Assignment type, when available."
          },
          "scheduledAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "New confirmed shooting start. Always present; `null` means the appointment was cleared (reschedule pending).\n"
          }
        }
      },
      "EstimatedDeliveryUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "assignmentId",
          "estimatedDeliveryAt"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "ESTIMATED_DELIVERY_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "assignmentType": {
            "type": "string",
            "description": "Assignment type, when available."
          },
          "estimatedDeliveryAt": {
            "type": "string",
            "format": "date",
            "description": "Estimated delivery date (date-only).",
            "example": "2026-07-02"
          }
        }
      },
      "MarketingMaterialsReadyEvent": {
        "type": "object",
        "required": [
          "event",
          "timestamp",
          "propertyId",
          "targetPlatform"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "MARKETING_MATERIALS_READY"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2023-01-15T12:45:00Z"
          },
          "propertyId": {
            "type": "string",
            "format": "uuid",
            "description": "Real estate property id."
          },
          "targetPlatform": {
            "type": "string",
            "description": "Target platform the materials were prepared for."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "description": "JWT Authentication. Enter your token in the format: Bearer {token}",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "parameters": {
      "EventTypeHeader": {
        "name": "X-Event-Type",
        "in": "header",
        "required": true,
        "description": "The event name. Matches the `event` field in the body.",
        "schema": {
          "type": "string",
          "example": "ASSIGNMENT_STATUS_UPDATED"
        }
      }
    }
  },
  "webhooks": {
    "visualsReady": {
      "post": {
        "summary": "Visuals ready",
        "description": "Sent when materials (visuals, documents, or other deliverables) are ready for download. On receipt, call the Materials API to retrieve the actual files.\n",
        "operationId": "onVisualsReady",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VisualsReadyEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "photographerBooked": {
      "post": {
        "summary": "Photographer booked",
        "description": "Sent when a photographer (creative) has accepted an assignment.",
        "operationId": "onPhotographerBooked",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhotographerBookedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "orderStatusUpdated": {
      "post": {
        "summary": "Order status updated",
        "description": "Sent when an order transitions between statuses.",
        "operationId": "onOrderStatusUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderStatusUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "assignmentStatusUpdated": {
      "post": {
        "summary": "Assignment status updated",
        "description": "Sent when an assignment transitions between statuses. May also be sent as a same-status nudge carrying refreshed logistics fields.\n",
        "operationId": "onAssignmentStatusUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssignmentStatusUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "appointmentDateUpdated": {
      "post": {
        "summary": "Appointment date updated",
        "description": "Sent when an assignment's shooting appointment date changes. `scheduledAt` is always present and is `null` when the appointment was cleared (reschedule pending).\n",
        "operationId": "onAppointmentDateUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppointmentDateUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "estimatedDeliveryUpdated": {
      "post": {
        "summary": "Estimated delivery updated",
        "description": "Sent when an assignment's estimated delivery date changes.",
        "operationId": "onEstimatedDeliveryUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimatedDeliveryUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "marketingMaterialsReady": {
      "post": {
        "summary": "Marketing materials ready",
        "description": "Sent when marketing materials for a property are ready for a target platform.",
        "operationId": "onMarketingMaterialsReady",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MarketingMaterialsReadyEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    }
  }
}
```