# Update Webhooks {% hint style="success" %} First, obtain an access token to get started [here](/getting-started/authentication.md). {% endhint %} Update existing webhooks to modify their configurations, such as changing the event types, endpoint URL or authentication details. Provide the updated `WebhookInput` object, including the webhook ID, to apply the changes. The mutation returns the updated webhook(s).
Schema ```graphql type Mutation { """ Mutation to update one or more existing webhooks. """ updateWebhooks( """ A list of WebhookUpdateInput objects, each containing the ID of the webhook to update and the fields to modify. """ input: [WebhookUpdateInput!]! ): [Webhook!] } """ Input type for updating an existing webhook. """ input WebhookUpdateInput { """ Unique identifier for the webhook to be updated. """ id: ID! """ Updated name for the webhook, chosen by the user. """ name: String """ Updated list of event types the webhook will subscribe to. """ eventTypes: [EventType!] """ Updated configuration settings for the endpoint. """ endpointConfig: EndpointConfigInput """ Optional filters to apply to webhook events. Supports filtering by org_ids, site_ids, building_ids, floor_ids, room_ids, zone_ids, and mac_addresses. example: { org_ids: ["org_1", "org_2"], site_ids: ["site_1", "site_2"], building_ids: ["building_1", "building_2"], floor_ids: ["space_1", "space_2"], room_ids: ["room_1", "room_2"], zone_ids: ["zone_1", "zone_2"], mac_addresses: ["01-23-45-67", "ab-cd-ef-gh"] } """ filters: JSON """ When set to true, webhooks will only be sent when the value of the event changes from the previous value. Defaults to false. """ send_on_value_change: Boolean } """ Enum representing the different types of events that can be tracked with a webhook. """ enum EventType { """ Event type for floor occupancy updates. """ FLOOR_OCCUPANCY """ Event type for room occupancy updates. """ ROOM_OCCUPANCY """ Event type for zone occupancy updates. """ ZONE_OCCUPANCY """ Event type for detection coordinate updates. """ DETECTIONS """ Event type for traffic (enter/exits) updates. """ TRAFFIC } """ Input type for endpoint configuration, specifying the webhook destination and authentication settings. """ input EndpointConfigInput { """ The URL of the webhook endpoint where events will be sent. Only HTTPS URLs are supported. """ url: String! """ The HTTP timeout in seconds for the request to complete. Acceptable values range from 1 to 15. """ httpTimeout: Int! """ Optional API key configuration for header-based authentication. """ apiKey: ApiKeyInput """ Optional basic authentication configuration, providing a username and password. """ basicAuth: BasicAuthInput } """ Input type for API key configuration, defining the API key and the header name to be used. """ input ApiKeyInput { """ The header key name to be used for the API key, such as 'x-api-key'. """ key: String! """ The actual API key value for authentication. """ value: String! } """ Input type for basic authentication, specifying username and password credentials. """ input BasicAuthInput { """ The username for basic authentication. """ username: String! """ The password for basic authentication, associated with the username. """ password: String! } """ A type representing API credentials. """ type ApiKey { """ This key represents the type of header key, often specifying the header name to be used in authentication, such as 'x-api-key'. """ key: String! """ The actual API key value used for authentication in requests. """ value: String! } """ A type representing basic authentication configuration. """ type BasicAuth { """ The username for basic authentication. """ username: String! """ The password associated with the username for basic authentication. """ password: String! } """ Configuration settings for the endpoint where the webhook sends data. """ type EndpointConfig { """ The URL of the webhook endpoint where events will be sent. Only HTTPS URLs are supported. """ url: String! """ The HTTP timeout in seconds for the request to complete. Acceptable values are between 1 and 15. """ httpTimeout: Int! """ Optional API key configuration for header-based authentication. """ apiKey: ApiKey """ Optional basic authentication configuration, including username and password. """ basicAuth: BasicAuth } """ Represents a webhook subscription, containing information on the events it tracks and the endpoint configuration. """ type Webhook { """ A unique identifier for the webhook subscription. """ id: ID! """ A user-defined name for the webhook, useful for identifying the webhook purpose. """ name: String! """ A list of event types that the webhook subscribes to, such as FLOOR_OCCUPANCY, ROOM_OCCUPANCY, etc. """ eventTypes: [EventType!]! """ Configuration details for the endpoint, including URL, timeout, and authentication options. """ endpointConfig: EndpointConfig! """ Optional filters to apply to webhook events. Supports filtering by various IDs and MAC addresses. example: { org_ids: ["org_1", "org_2"], site_ids: ["site_1", "site_2"], building_ids: ["building_1", "building_2"], floor_ids: ["space_1", "space_2"], room_ids: ["room_1", "room_2"], zone_ids: ["zone_1", "zone_2"], mac_addresses: ["01-23-45-67", "ab-cd-ef-gh"] } """ filters: JSON """ When set to true, webhooks will only be sent when the value of the event changes from the previous value. Defaults to false. """ send_on_value_change: Boolean } ```
Mutation ```graphql mutation UpdateWebhooks ($input: [WebhookUpdateInput!]!) { updateWebhooks(input: $input) { id name event_types endpoint_config { url http_timeout api_key { key value } basic_auth { username password } } } } #variables { "input": [{ "id": "webhook_2oqujQF2pRZO8BqPgT8dWkf4Swb", "name": "My Webhook", "event_types": ["FLOOR_OCCUPANCY"], "endpoint_config": { "url": "https://customer.api.com/webhooks", "http_timeout": 10, "api_key": { "key": "x-api-key", "value": "akfsdl;jf;alksjdfiuhwiefhsks" }, "basic_auth": { "username": "bob", "password": "letmein" } } }, { "id": "webhook_2oqujRtbTdX1KTA0olXvAtftGWA" "name": "Another Webhook", "event_types": ["ROOM_OCCUPANCY", "DETECTIONS"], "endpoint_config": { "url": "https://another.customer.api.com/webhooks", "http_timeout": 15 } }] } ```
Response (Example) ```json { "data": { "updateWebhooks": [ { "id": "webhook_2oqujQF2pRZO8BqPgT8dWkf4Swb", "name": "My Webhook", "event_types": ["FLOOR_OCCUPANCY"], "endpoint_config": { "url": "https://customer.api.com/webhooks", "http_timeout": 10, "api_key": { "key": "x-api-key", "value": "akfsdl;jf;alksjdfiuhwiefhsks" }, "basic_auth": { "username": "bob", "password": "letmein" } } }, { "id": "webhook_2oqujRtbTdX1KTA0olXvAtftGWA", "name": "Another Webhook", "event_types": ["ROOM_OCCUPANCY", "DETECTIONS"], "endpoint_config": { "url": "https://another.customer.api.com/webhooks", "http_timeout": 15, "api_key": null, "basic_auth": null } } ] } } ```
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.butlr.io/real-time-occupancy/manage-webhooks/update-webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.