# Update a webhook.

Update a webhook. This endpoint requires the `personio:webhooks:write` scope.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Webhooks Management API",
    "version": "2.0.0",
    "description": "Endpoints to manage webhooks."
  },
  "servers": [
    {
      "url": "https://api.personio.de"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v2/webhooks/{id}": {
      "patch": {
        "summary": "Update a webhook.",
        "description": "Update a webhook. This endpoint requires the `personio:webhooks:write` scope.",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The unique identifier of the webhook to be updated.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-path-examples": {
          "PATCH Valid request": {
            "value": "/v2/webhooks/2e4324b0-1b0e-11ee-a7f7-e37ffd9b3a44"
          },
          "PATCH Invalid URL": {
            "value": "/v2/webhooks/2e4324b0-1b0e-11ee-a7f7-e37ffd9b3a44"
          },
          "PATCH Invalid Hostname": {
            "value": "/v2/webhooks/2e4324b0-1b0e-11ee-a7f7-e37ffd9b3a44"
          }
        },
        "requestBody": {
          "$ref": "#/components/requestBodies/UpdateWebhookRequest"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/WebhookUpdatedResponse"
          },
          "400": {
            "$ref": "#/components/responses/WebhookUpdateBadRequestErrorResponse"
          },
          "401": {
            "$ref": "#/components/responses/WebhookUpdateInvalidAuthenticationErrorResponse"
          },
          "403": {
            "$ref": "#/components/responses/WebhookAccessForbiddenErrorResponse"
          },
          "404": {
            "$ref": "#/components/responses/WebhookNotFoundErrorResponse"
          },
          "409": {
            "$ref": "#/components/responses/WebhookUpdateConflictErrorResponse"
          },
          "422": {
            "$ref": "#/components/responses/WebhookUpdateUnprocessableEntityErrorResponse"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Webhook": {
        "description": "Webhook schema",
        "type": "object",
        "required": [
          "id",
          "url",
          "description"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The identifier for the webhook.",
            "readOnly": true
          },
          "url": {
            "type": "string",
            "format": "url",
            "description": "The url that should be called once a webhook event is fired. This should be an HTTPS endpoint."
          },
          "description": {
            "type": "string",
            "description": "The description of the webhook configuration."
          },
          "token": {
            "type": "string",
            "description": "The token used to authenticate the request on the webhook's URL. The callback will include this exact value in the Authorization header for authentication. If a specific format is required (e.g., \"Bearer\" or \"Basic\"), please include the desired prefix (such as \"Bearer \" or \"Basic \") at the beginning of the token when configuring it, as no prefix will be added automatically."
          },
          "status": {
            "$ref": "#/components/schemas/WebhookStatus"
          },
          "enabled_events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Contains the list of enabled events."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp of when the webhook was created in UTC.",
            "readOnly": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp of when the webhook was last updated in UTC. Carries an initial value of created_at.",
            "readOnly": true
          },
          "auth_type": {
            "type": "string",
            "description": "The authentication type used for webhook delivery requests.\n- NONE: No authentication headers will be sent.\n- TOKEN: (default) A static token will be sent in the Authorization header.\n- CUSTOM: Up to 3 custom HTTP headers will be sent as specified in `custom_headers`.\n",
            "enum": [
              "NONE",
              "TOKEN",
              "CUSTOM"
            ],
            "default": "TOKEN"
          },
          "custom_headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "description": "Header value"
            },
            "description": "A map of custom HTTP headers to include in webhook delivery requests.\nOnly allowed if `auth_type` is `CUSTOM`.\n- Maximum of 3 headers (map entries).\n- Header names (keys) must not match or start with any of the following (case-insensitive):\n  host, content-length, transfer-encoding, connection, upgrade, te, trailer, expect, content-type\n- Example:\n    {\n      \"X-My-Auth\": \"abc123\",\n      \"X-Tracking\": \"track-me\"\n    }\n"
          }
        }
      },
      "WebhookStatus": {
        "type": "string",
        "enum": [
          "ENABLED",
          "DISABLED"
        ],
        "description": "The status of the webhook configuration."
      },
      "UpdateWebhookRequest": {
        "description": "Update Webhook request schema",
        "type": "object",
        "properties": {
          "url": {
            "$ref": "#/components/schemas/Webhook/properties/url"
          },
          "description": {
            "$ref": "#/components/schemas/Webhook/properties/description"
          },
          "status": {
            "$ref": "#/components/schemas/WebhookStatus"
          },
          "auth_type": {
            "$ref": "#/components/schemas/Webhook/properties/auth_type"
          },
          "token": {
            "$ref": "#/components/schemas/Webhook/properties/token"
          },
          "custom_headers": {
            "$ref": "#/components/schemas/Webhook/properties/custom_headers"
          },
          "enabled_events": {
            "$ref": "#/components/schemas/Webhook/properties/enabled_events"
          }
        }
      }
    },
    "requestBodies": {
      "UpdateWebhookRequest": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/UpdateWebhookRequest"
            },
            "examples": {
              "PATCH Valid request": {
                "$ref": "#/components/examples/ValidUpdateWebhookRequestPayload"
              },
              "PATCH Invalid URL": {
                "$ref": "#/components/examples/InvalidUrlUpdateWebhookRequestPayload"
              },
              "PATCH Invalid Hostname": {
                "$ref": "#/components/examples/InvalidHostnameWebhookRequestPayload"
              }
            }
          }
        }
      }
    },
    "responses": {
      "WebhooksResponse": {
        "description": "Successful list all webhooks response.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "_data": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Webhook"
                  }
                },
                "_meta": {
                  "description": "This object represents the metadata information for an object. It's a set of arbitrary key/value attributes such as `links`.",
                  "type": "object",
                  "readOnly": true,
                  "properties": {
                    "links": {
                      "type": "object",
                      "additionalProperties": {
                        "description": "This objects represents a hyperlink.",
                        "type": "object",
                        "readOnly": true,
                        "properties": {
                          "href": {
                            "type": "string",
                            "format": "uri"
                          }
                        },
                        "additionalProperties": true
                      },
                      "example": {
                        "links": {
                          "self": {
                            "href": "https://api.personio.de/v2/person?cursor=<current-cursor>"
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "examples": {
              "List all webhooks": {
                "$ref": "#/components/examples/ListAllWebhooksResponse"
              },
              "List all webhooks where enabled_events contains person.updated": {
                "$ref": "#/components/examples/ListAllWebhooksEnabledEventFilterResponse"
              },
              "List all webhooks where status is enabled": {
                "$ref": "#/components/examples/ListAllWebhooksStatusFilterResponse"
              }
            }
          }
        }
      },
      "WebhookCreatedResponse": {
        "description": "The webhook was successfully created.",
        "content": {
          "application/json": {
            "schema": {
              "description": "This is an object that is returned whenever a new resource is created. It contains the unique identifier for the created resource and optionally a link that can be used to retrieve it.",
              "properties": {
                "id": {
                  "readOnly": true,
                  "type": "string",
                  "example": "some-random-id",
                  "description": "The id of the created resource."
                },
                "_meta": {
                  "$ref": "#/components/responses/WebhooksResponse/content/application~1json/schema/properties/_meta"
                }
              }
            },
            "examples": {
              "Valid request": {
                "$ref": "#/components/examples/WebhookCreatedResponse"
              },
              "Valid request (No Auth)": {
                "$ref": "#/components/examples/WebhookCreatedResponse"
              },
              "Valid request (Custom Auth)": {
                "$ref": "#/components/examples/WebhookCreatedResponse"
              }
            }
          }
        }
      },
      "WebhookUpdatedResponse": {
        "description": "The webhook was successfully updated.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/responses/WebhookCreatedResponse/content/application~1json/schema"
            },
            "examples": {
              "PATCH Valid request": {
                "$ref": "#/components/examples/WebhookUpdatedResponse"
              }
            }
          }
        }
      },
      "WebhookNotFoundErrorResponse": {
        "description": "The webhook could not be found.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/WebhookTestEventBadRequest/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "Resource Not Found": {
                "$ref": "#/components/examples/WebhookNotFoundErrorResponse"
              }
            }
          }
        }
      },
      "WebhookAccessForbiddenErrorResponse": {
        "description": "Access to the webhook is forbidden.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/WebhookTestEventBadRequest/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "Access Forbidden": {
                "$ref": "#/components/examples/WebhookAccessForbiddenErrorResponse"
              }
            }
          }
        }
      },
      "WebhookUpdateBadRequestErrorResponse": {
        "description": "The webhook could not be updated due to faulty input payload.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/WebhookTestEventBadRequest/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "Invalid status field": {
                "$ref": "#/components/examples/InvalidStatusPayloadResponse"
              }
            }
          }
        }
      },
      "WebhookUpdateInvalidAuthenticationErrorResponse": {
        "description": "The webhook could not be updated due to invalid authentication.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/WebhookTestEventBadRequest/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "Invalid authentication type": {
                "$ref": "#/components/examples/InvalidAuthenticationPayloadResponse"
              }
            }
          }
        }
      },
      "WebhookUpdateUnprocessableEntityErrorResponse": {
        "description": "The webhook could not be updated due to semantically incorrect input payload.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/WebhookTestEventBadRequest/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "PATCH Invalid URL": {
                "$ref": "#/components/examples/InvalidUrlPayloadResponse"
              },
              "PATCH Invalid Hostname": {
                "$ref": "#/components/examples/InvalidHostnamePayloadResponse"
              }
            }
          }
        }
      },
      "WebhookUpdateConflictErrorResponse": {
        "description": "The webhook could not be updated due to a failed precondition.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/WebhookTestEventBadRequest/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "Duplicate URL": {
                "$ref": "#/components/examples/ConflictPayloadResponse"
              }
            }
          }
        }
      },
      "WebhookTestEventBadRequest": {
        "description": "Bad request - invalid event name, event not enabled, or missing required payload data.",
        "content": {
          "application/problem+json": {
            "schema": {
              "type": "object",
              "description": "This object represents an error response.",
              "properties": {
                "personio_trace_id": {
                  "type": "string",
                  "example": "aswo3f-a202lfso-312123sld-1230ddd",
                  "description": "A unique ID that was created for this error."
                },
                "timestamp": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2021-05-28T11:17:30.000Z",
                  "description": "The timestamp of when the error occurred."
                },
                "errors": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "title": {
                        "type": "string",
                        "example": "Not found",
                        "description": "The title of the error."
                      },
                      "detail": {
                        "type": "string",
                        "example": "The requested resource was not found.",
                        "description": "A short description about the error."
                      },
                      "type": {
                        "type": "string",
                        "format": "uri",
                        "example": "https://developer.personio.de/reference/errors#common.requested_resource_not_found",
                        "description": "A link to the developer hub where more information can be found for the encountered error."
                      },
                      "_meta": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "examples": {
              "400 missing required payload data": {
                "$ref": "#/components/examples/TestEventMissingPayloadDataResponse"
              }
            }
          }
        }
      }
    },
    "examples": {
      "ValidUpdateWebhookRequestPayload": {
        "value": {
          "url": "https://example.com/callback",
          "description": "Sample webhook",
          "status": "DISABLED"
        }
      },
      "InvalidUrlUpdateWebhookRequestPayload": {
        "value": {
          "url": "http://example.com/callback",
          "description": "Sample webhook",
          "status": "DISABLED"
        }
      },
      "InvalidHostnameWebhookRequestPayload": {
        "value": {
          "url": "https://10.1.1.1/callback",
          "description": "Sample webhook",
          "token": "eyJraWQiOiAnJYjE1NzEyZC00YzFmLTUxODEtYWExNC03MjdlZmViNmYw",
          "enabled_events": [
            "person.updated"
          ]
        }
      },
      "WebhookUpdatedResponse": {
        "value": {
          "id": "5d06ebb0-f4a3-11ed-b962-7fc202e0eb99"
        }
      },
      "WebhookAccessForbiddenErrorResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Access denied",
              "detail": "Access denied to perform webhook operations"
            }
          ]
        }
      },
      "WebhookNotFoundErrorResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Webhook not found",
              "detail": "No webhook found matching the given id"
            }
          ]
        }
      },
      "InvalidStatusPayloadResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Input must be a valid JSON",
              "detail": "Invalid value for field: status. Supported values are [ENABLED, DISABLED]"
            }
          ]
        }
      },
      "InvalidUrlPayloadResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "The URL is considered invalid.",
              "detail": "URL does not use HTTPS scheme."
            }
          ]
        }
      },
      "InvalidHostnamePayloadResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "The URL is considered invalid.",
              "detail": "Hostname does not resolve to a valid address."
            }
          ]
        }
      },
      "ConflictPayloadResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Duplicate URL",
              "detail": "Another webhook configuration with identical URL exists.",
              "_meta": {
                "id": "89821e24-1b15-11ee-8f8e-430f660e2f9e"
              }
            }
          ]
        }
      },
      "InvalidAuthenticationPayloadResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Invalid authentication",
              "detail": "The authentication type is unsupported."
            }
          ]
        }
      }
    }
  }
}
```