# Get a webhook. Get a webhook. This endpoint requires the `personio:webhooks:read` 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}": { "get": { "summary": "Get a webhook.", "description": "Get a webhook. This endpoint requires the `personio:webhooks:read` scope.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the webhook to be retrieved.", "schema": { "type": "string" } } ], "x-path-examples": { "GET Valid request": { "value": "/v2/webhooks/533e7206-f4a3-11ed-9c8b-436fad0b82d1" } }, "responses": { "200": { "$ref": "#/components/responses/SingleWebhookResponse" }, "401": { "$ref": "#/components/responses/WebhookUpdateInvalidAuthenticationErrorResponse" }, "403": { "$ref": "#/components/responses/WebhookAccessForbiddenErrorResponse" }, "404": { "$ref": "#/components/responses/WebhookNotFoundErrorResponse" } } } } }, "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." } }, "responses": { "SingleWebhookResponse": { "description": "Successful single webhooks response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" }, "examples": { "GET Valid request": { "$ref": "#/components/examples/GetWebhookResponse" } } } } }, "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" } } } } }, "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" } } } } }, "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": { "GetWebhookResponse": { "value": { "id": "533e7206-f4a3-11ed-9c8b-436fad0b82d1", "url": "https://example.com/callback", "description": "An enabled configuration.", "status": "ENABLED", "token": "eyJraWQiOiI4YjE1NzEyZC00YzFmLTUxODEtYWExNC03MjdlZmViNmYwMjkiL", "enabled_events": [ "person.updated", "absence.created" ], "created_at": "2021-05-28T11:17:30Z", "updated_at": "2021-05-28T11:17:30Z" } }, "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" } ] } }, "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." } ] } } } } } ```