> ## Documentation Index
> Fetch the complete documentation index at: https://getconvoy.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Endpoints
An endpoint is a valid [HTTP URL](https://datatracker.ietf.org/doc/html/rfc7230) that can receive webhook events. It can be configured with a number of attributes which include an `http timeout` which denotes how long Convoy should wait for a response before timing out, an `alert configuration` setting which gives you the option to get notified when an endpoint's status changes, a `rate limit` setting which allows you to match your consumers own rate limit, and an `authentication` setting which allows your consumer set an additional level of security on the endpoint.
For **ping on create/update**, **TLS**, and **dispatcher** settings (`skip_ping_validation`, custom CA, allow/block lists), see [Endpoint verification and outbound connections](/product-manual/endpoint-verification).
To provision **many endpoints** (and per-endpoint subscriptions) in one project via the API, see [Bulk onboard](/guides/api-onboarding#bulk-onboard) in [API-driven onboarding](/guides/api-onboarding).
### Endpoint State
An endpoint can have any of the states below:
* `Active`: This state means the endpoint is responding normally, and Convoy will continue to send events to it.
* `Inactive`: This means the endpoint has consecutively failed to process events. In this state, all new events will be set to the `Discarded` state and **will not be sent** to the endpoint. To re-activate the endpoint -- retry any failed or discarded event delivery, if it's successful, the endpoint will be set to `active`. Then you can batch retry all failed events that weren't processed while the endpoint was `inactive`.
* `Paused`: In this state, the endpoint has been manually disabled to stop receiving events. All new events will be set to the `Discarded` state and **will not be sent** to the endpoint. To re-activate the endpoint, un-pause the endpoint, and it will be set to `active`.
* `Pending`: This state indicates that the endpoint was previously `Inactive` and a failed or discarded event delivery is being resent to the endpoint. If successful, the endpoint will be set to `Active`.
### Zero Downtime Key Rotation
Because webhooks rely on a shared secret that needs to be rotated periodically to be kept safe, Convoy ships with a mechanism for zero downtime key rotation which is crucial for webhooks as it ensures continuous and secure operations. It facilitates regular cryptographic key rotations, mitigating risks associated with key compromises, while ensuring there's no service interruption, which is vital for real-time processing of webhooks events. It also aids in meeting regulatory compliance, maintaining clear audit trails, and can be automated to reduce operational burdens of key rotations. Additionally, it fosters customer trust by showcasing a commitment to security and service availability,
This can be triggered from both the API -- [this endpoint](/api-reference/endpoints/roll-endpoint-secret) and the dashboard, see below: 
Once the secret is expired, Convoy will send more than one message digest pending the full expiration of the old secret. You can learn more about [signatures](https://getconvoy.io/docs/product-manual/signatures)
### Endpoint authentication
Endpoint authentication is a scenario where the endpoint owner needs to specify an authentication mechanism separate from signatures so Convoy can call the destination successfully. Convoy supports **API key**, **OAuth2 client credentials**, and **HTTP Basic** authentication on outbound deliveries.
### Basic authentication (outbound)
When the endpoint expects [HTTP Basic authentication](https://datatracker.ietf.org/doc/html/rfc7617), set authentication `type` to `basic_auth` and set `basic_auth` with JSON fields **`username`** and **`password`**. Convoy sends an `Authorization: Basic` header built as Base64(`username` + `:` + `password`).
Basic auth for endpoints is gated by a **Premium license** (entitlement `basic_auth_endpoint_auth`) and the organisation **early adopter** flag with feature key `basic-auth-endpoint` (enable under Organisation Settings → Early Adopter Features). Until both are enabled, create/update and delivery behaviour will reject or skip Basic auth as implemented in your Convoy version.
See also [Feature flags](/resources/feature-flags) and the [OpenAPI specification](/api-reference/welcome) (`authentication.type`: `api_key` | `oauth2` | `basic_auth`).
### mTLS Client Certificate Support
Some endpoints require mutual TLS (mTLS) authentication, where both the client and server present certificates to establish a secure connection. Convoy supports mTLS client certificates for endpoints that require certificate-based authentication.
When you configure an mTLS client certificate on an endpoint, Convoy will present the client certificate during webhook delivery to that endpoint. This is especially useful for enterprise integrations that require certificate-based authentication.
To configure mTLS:
1. Provide your client certificate (PEM format)
2. Provide your client private key (PEM format)
3. Configure these in the endpoint settings via the API or dashboard
Convoy handles certificate presentation automatically during delivery. This feature requires an Enterprise license.
### OAuth2 Client Credentials Authentication
Some endpoints require OAuth2 authentication using the client credentials flow. Convoy supports OAuth2 token exchange for endpoints that need to authenticate with an OAuth2 provider before receiving webhooks.
When you configure OAuth2 authentication on an endpoint, Convoy automatically exchanges client credentials for an access token and includes it in the `Authorization` header when delivering webhooks. Tokens are cached and refreshed automatically before expiration.
Convoy supports two OAuth2 authentication types:
* **Shared Secret**: Uses `client_id` and `client_secret` for token exchange
* **Client Assertion**: Uses JWT client assertion with ES256 signing (requires JWK with private key)
To configure OAuth2:
1. Provide your OAuth2 token URL
2. Provide your client ID
3. Choose authentication type:
* For shared secret: provide your `client_secret`
* For client assertion: provide JWK with private key, issuer, and subject
4. Configure these in the endpoint settings via the API or dashboard
Convoy handles token exchange and refresh automatically during delivery. This feature requires a Premium license and the OAuth Token Exchange early adopter feature flag enabled for your organization.
### Outbound authentication FAQ
* **Which authentication types are supported?** **`api_key`** (static header name and value), **`oauth2`** (token URL + **shared secret** with `client_id` / `client_secret`, or **client assertion** with a JWK and JWT), **`basic_auth`** when your license and organisation early adopter flag allow it, plus **mTLS** client certificates for TLS client auth. See the [OpenAPI specification](/api-reference/welcome) for request shapes.
* **Does OAuth2 cover “client ID and client secret”?** Yes — use the **shared secret** OAuth2 type with your provider’s token URL, `client_id`, and `client_secret`. For providers that require a JWT assertion instead of a secret, use **client assertion** as described above.
* **Can I send multiple custom headers or arbitrary header maps?** Not as a first-class endpoint auth type. The **`api_key`** type is a **single** `header_name` / `header_value` pair. For more complex cases, discuss options with your Convoy contact (workarounds may be product-specific).
* **How does Basic Auth differ from mTLS?** Basic Auth adds an `Authorization: Basic` header. mTLS presents a client certificate during the TLS handshake. They address different server requirements and are configured separately.
### Endpoint URL templates
An endpoint URL can include template tokens so a single endpoint definition matches many concrete destination URLs. Use single-brace placeholders such as `{tenant_id}` in the **path or query** of the URL:
```
https://api.example.com/v1/{tenant_id}/webhooks
https://api.example.com/webhooks?team={team_id}
```
This works with **dynamic events**, where each event supplies its own concrete `url`. Convoy matches that concrete URL against your templated endpoints and delivers to the URL from the event; it does not substitute tokens from the payload. The event's `url` must itself be concrete, and a delivery to a templated endpoint with no concrete target URL is discarded.
Tokens are only allowed in the path or query. The scheme and host cannot be templated (for example `https://{tenant}.example.com/...` is rejected), and a token name must start with a letter or underscore.
Endpoint URL templates are a **Premium** feature. Enable the **Endpoint URL Templates** early adopter feature for your organisation under Organisation Settings → Early Adopter Features. See [Feature flags](/resources/feature-flags).
### Content Type
Endpoints can be configured to send webhook payloads in different content types. By default, Convoy sends events as `application/json`. You can also configure endpoints to send events as `application/x-www-form-urlencoded` for endpoints that expect form-encoded data instead of JSON.
Configure the content type in your endpoint settings via the API or dashboard.
### Endpoint Owner ID
Endpoint Owner ID is a unique ID for identifying a group of endpoints. It is useful for fanning out an event to multiple endpoints and creating portal link for multiple endpoints. It is typically set by you, the user and should have meaningful significance within your internal systems, serving the purpose of logically grouping endpoints.
### Portal Links
A [Portal Link](https://getconvoy.io/docs/product-manual/portal-links) is used to generate a consumer-facing dashboard to display information on an endpoint's event deliveries. The portal link serves as a medium to quickly generate portals for users to review and debug events from a publisher. You can generate one time links via the dashboard or long-use links to be embedded in your dashboards via the API. To learn more, click [here](https://getconvoy.io/docs/product-manual/portal-links)
