# List webhooks.

Returns a list of webhooks. 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": {
      "get": {
        "summary": "List webhooks.",
        "description": "Returns a list of webhooks. This endpoint requires the `personio:webhooks:read` scope.",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "enabled_events",
            "in": "query",
            "description": "Enables filtering by event. Suitable to fetch a list of webhooks configured for a specific event.\n",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Enables filtering by status. Suitable to fetch a list of webhooks in a particular status. For eg., all enabled webhooks.\n",
            "schema": {
              "$ref": "#/components/schemas/WebhookStatus"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "example": 100,
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            },
            "description": "The amount of resources to be returned per one request. It can range between 1 and 200,  and the default is 100."
          },
          {
            "in": "query",
            "name": "cursor",
            "example": "cur_82sQwR2eZvKilo2duNh219Kw",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The pagination cursor to navigate over to the next list of resources. If you pass a specific limit to your  request, or you rely on the default value of the number of resources to be returned, then your subsequent call has to include the cursor in order to retrieve the next list of resources. If cursor is missing,  the first page is returned."
          }
        ],
        "x-path-examples": {
          "List all webhooks": {
            "value": ""
          },
          "List all webhooks where enabled_events contains person.updated": {
            "value": "enabled_events=person.updated"
          },
          "List all webhooks where status is enabled": {
            "value": "status=ENABLED"
          },
          "Invalid status filter": {
            "value": "status=invalid"
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/WebhooksResponse"
          },
          "400": {
            "$ref": "#/components/responses/WebhookBadFilterErrorResponse"
          },
          "401": {
            "$ref": "#/components/responses/WebhookInvalidAuthenticationErrorResponse"
          },
          "403": {
            "$ref": "#/components/responses/WebhookAccessForbiddenErrorResponse"
          }
        }
      }
    }
  },
  "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": {
      "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"
              }
            }
          }
        }
      },
      "WebhookBadFilterErrorResponse": {
        "description": "The filters specified with the request are faulty.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/responses/WebhookTestEventBadRequest/content/application~1problem%2Bjson/schema"
            },
            "examples": {
              "Invalid status filter": {
                "$ref": "#/components/examples/InvalidStatusFilterResponse"
              }
            }
          }
        }
      },
      "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"
              }
            }
          }
        }
      },
      "WebhookInvalidAuthenticationErrorResponse": {
        "description": "The webhook could not be created 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": {
      "ListAllWebhooksResponse": {
        "value": {
          "_data": [
            {
              "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:30+00:00",
              "updated_at": "2021-05-28T11:17:30+00:00"
            },
            {
              "id": "5d06ebb0-f4a3-11ed-b962-7fc202e0eb99",
              "url": "https://webhooks.fyi/sink",
              "description": "A disabled configuration.",
              "status": "DISABLED",
              "token": "ZkUraWQiOiI4YjE1NzEyZC00YzFmLTUxODEtYWExNC03MjdlZmViNmYwXuNJ",
              "enabled_events": [
                "person.created",
                "absence.created"
              ],
              "created_at": "2021-05-28T11:17:30+00:00",
              "updated_at": "2021-06-28T11:17:30+00:00"
            }
          ],
          "_meta": {
            "links": {
              "next": {
                "href": "https://api.personio.de/v2/webhooks?cursor=cur_AKbEjPZsArTP07gbhAaIUILluT52MvY7aab1jJTR3PgwQZ1BzQjplnq8"
              }
            }
          }
        }
      },
      "ListAllWebhooksEnabledEventFilterResponse": {
        "value": {
          "_data": [
            {
              "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:30+00:00",
              "updated_at": "2021-05-28T11:17:30+00:00"
            }
          ],
          "_meta": {
            "links": {
              "next": {
                "href": "https://api.personio.de/v2/webhooks?cursor=cur_AKbEjPZsArTP07gbhAaIUILluT52MvY7aab1jJTR3PgwQZ1BzQjplnq8"
              }
            }
          }
        }
      },
      "ListAllWebhooksStatusFilterResponse": {
        "value": {
          "_data": [
            {
              "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:30+00:00",
              "updated_at": "2021-05-28T11:17:30+00:00"
            }
          ],
          "_meta": {
            "links": {
              "next": {
                "href": "https://api.personio.de/v2/webhooks?cursor=cur_AKbEjPZsArTP07gbhAaIUILluT52MvY7aab1jJTR3PgwQZ1BzQjplnq8"
              }
            }
          }
        }
      },
      "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"
            }
          ]
        }
      },
      "InvalidStatusFilterResponse": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30Z",
          "errors": [
            {
              "title": "Invalid value for filter: status",
              "detail": "Invalid value for filter: status. Supported values are [ENABLED, DISABLED]"
            }
          ]
        }
      },
      "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."
            }
          ]
        }
      }
    }
  }
}
```