---
title: "Create a Webhook"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Create a Webhook

`POST /webhooks`

Create a `Webhook` to receive webhook events for specified entities (e.g., `transfer`, `merchant`) to a URL provided by you. When an enabled event occurs, Finix sends a POST request to this URL with the webhook event payload.

{% admonition type="info" %}
The response includes a `secret_signing_key`. Store this value securely. It is used to verify that incoming payloads were sent by Finix.
{% /admonition %}

**Authentication**

Set `authentication.type` to control how Finix authenticates requests to your endpoint:
- `NONE` (default) — No authentication header is sent
- `BASIC` — Provide `authentication.basic.username` and `authentication.basic.password`
- `BEARER` — Provide `authentication.bearer.token`

To learn how to add webhook authentication, see [Creating Authenticated Webhooks](/additional-resources/developers/webhooks/integrating-into-webhooks#creating-authenticated-webhooks).

**Event Filtering**

By default, a new `Webhook` subscribes to a standard set of events. Include `enabled_events` to override the default set of events and receive only specific entity/type combinations. See [Webhook Events](/additional-resources/developers/webhooks/webhook-events) for supported entities and event types.

## Headers

- `Finix-Version` string
- `Content-Type` string

## Request body

- union
  - CreateWebhookAllFields
    - `authentication` Authentication — Credentials included in webhook POST requests so your server can confirm each request originated from Finix. To learn about the different authentication methods, see [Managing Webhooks via API](/additional-resources/developers/webhooks/integrating-into-webhooks#managing-webhooks-via-api).
      - `basic` object — A basic authentication configuration provided by the user.
        - `password` string — A user-provided basic authentication password.
        - `username` string — A user-provided basic authentication username.
      - `bearer` object — A bearer authentication configuration.
        - `token` string — The string that Finix will send as the bearer token.
      - `type` 'NONE' | 'BASIC' | 'BEARER' — The type of authentication the `Webhook` will use: - `NONE` - No authentication will be used. - `BASIC` - Basic authentication. - `BEARER` - OAuth2 Bearer Token.
    - `enabled_events` object[] — A list of webhook events to enable for API entities. There can be only one enabled event object per `entity`. This list is optional and overrides default webhook events. See [Webhook Events](/additional-resources/developers/webhooks/webhook-events) to learn which events are automatically subscribed at creation. When included in a PUT request, this list replaces all previously configured events.
      - `entity` string — The API entity for which you want to receive webhook events.
      - `types` string[] — A list of webhook event types you want to receive for the specified `entity`. See the [Webhook Events](/additional-resources/developers/webhooks/webhook-events) guide to learn which values are accepted for each entity.
    - `nickname` string — A human-readable name for the `Webhook`.
    - `url` string, required — The HTTP or HTTPS URL to receive events. When an event occurs, Finix sends a POST request to this URL with the webhook event payload.
  - CreateWebhookMinimalFields
    - `url` string, required — The HTTP or HTTPS URL to receive events. When an event occurs, Finix sends a POST request to this URL with the webhook event payload.
  - CreateWebhookBasicAuthentication
    - `authentication` object — Credentials included in webhook POST requests so your server can confirm each request originated from Finix. To learn about the different authentication methods, see [Managing Webhooks via API](/additional-resources/developers/webhooks/integrating-into-webhooks#managing-webhooks-via-api).
      - `basic` object, required — A basic authentication configuration provided by the user.
        - `password` string, required — A user-provided basic authentication password.
        - `username` string, required — A user-provided basic authentication username.
      - `type` 'BASIC', required — The type of authentication the `Webhook` will use: - `BASIC` - Basic authentication.
    - `url` string, required — The HTTP or HTTPS URL to receive events. When an event occurs, Finix sends a POST request to this URL with the webhook event payload.
  - CreateWebhookBearerToken
    - `authentication` object — Credentials included in webhook POST requests so your server can confirm each request originated from Finix. To learn about the different authentication methods, see [Managing Webhooks via API](/additional-resources/developers/webhooks/integrating-into-webhooks#managing-webhooks-via-api).
      - `bearer` object, required — A bearer authentication configuration.
        - `token` string, required — The string that Finix will send as the bearer token.
      - `type` 'BEARER', required — The type of authentication the `Webhook` will use: - `BEARER` - OAuth2 Bearer Token.
    - `url` string, required — The HTTP or HTTPS URL to receive events. When an event occurs, Finix sends a POST request to this URL with the webhook event payload.
  - CreateWebhookEventFiltering
    - `enabled_events` object[] — A list of webhook events to enable for API entities. There can be only one enabled event object per `entity`. This list is optional and overrides default webhook events. See [Webhook Events](/additional-resources/developers/webhooks/webhook-events) to learn which events are automatically subscribed at creation. When included in a PUT request, this list replaces all previously configured events.
      - `entity` string — The API entity for which you want to receive webhook events.
      - `types` string[] — A list of webhook event types you want to receive for the specified `entity`. See the [Webhook Events](/additional-resources/developers/webhooks/webhook-events) guide to learn which values are accepted for each entity.
    - `url` string, required — The HTTP or HTTPS URL to receive callbacks. When an enabled event occurs, Finix sends a POST request to this URL with the webhook event payload.

## Response `201`

A single `Webhook`

- Webhook
  - `id` string — The ID of the resource.
  - `created_at` string, date-time — Timestamp of when the object was created.
  - `updated_at` string, date-time — Timestamp of when the object was last updated.
  - `application` string — ID of the `Application` the resource was created under.
  - `authentication` object — Credentials included in webhook POST requests so your server can confirm each request originated from Finix. To learn about the different authentication methods, see [Managing Webhooks via API](/additional-resources/developers/webhooks/integrating-into-webhooks#managing-webhooks-via-api).
    - `type` 'NONE' | 'BASIC' | 'BEARER' — The type of authentication the `Webhook` will use: - `NONE`: No authentication will be used. - `BASIC`: Basic authentication. - `BEARER`: OAuth2 Bearer Token.
  - `enabled` boolean — Whether the `Webhook` is enabled. Disabled webhooks will not receive events. - `true`: Events are sent to the `url`. - `false`: Events are not sent to the `url`.
  - `enabled_events` object[] — A list of webhook events to enable for API entities. There can be only one enabled event object per `entity`. This list is optional and overrides default webhook events. See [Webhook Events](/additional-resources/developers/webhooks/webhook-events) to learn which events are automatically subscribed at creation. When included in a PUT request, this list replaces all previously configured events.
    - `entity` string — The API entity for which you want to receive webhook events.
    - `types` string[] — A list of webhook event types you want to receive for the specified `entity`. See the [Webhook Events](/additional-resources/developers/webhooks/webhook-events) guide to learn which values are accepted for each entity.
  - `is_accepting_events` boolean — Whether the `Webhook` is currently accepting events; this field mirrors the `enabled` field.
  - `nickname` string — A human-readable name for the `Webhook`.
  - `previous_secret_expires_at` string, nullable — The time when the previous `secret_signing_key` expires. Set when the signing key is rotated; `null` on initial creation.
  - `secret_signing_key` string, nullable — Use this key to verify the `Finix-Signature` header on incoming webhook events, confirming the payload came from Finix, was not tampered with, and was sent recently. For details, see [Verifying Webhook Signatures](/additional-resources/developers/webhooks/integrating-into-webhooks#verifying-webhook-signatures-finix-signature).
  - `url` string — The HTTP or HTTPS URL to receive events. When an event occurs, Finix sends a POST request to this URL with the webhook event payload.
  - `_links` object — For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these `_links` to make your follow-up requests and quickly access relevant IDs.
    - `application` ApplicationLink — Link to the `Application` the request was made under.
      - `href` string
    - `self` Self — Link to the resource that was used in the request.
      - `href` string

## Other responses

- `400` — Bad Request. The server cannot process the request due to malformed syntax or invalid data.
- `401` — Unauthorized. Authentication is required and has failed or has not been provided.
- `403` — Forbidden. The client is authenticated but does not have permission to access the resource.
- `406` — Not Acceptable. The server could not accept the submitted request. Confirm how the request was formatted and submitted.
- `422` — Unprocessable Entity. The syntax of the request content was correct, but the server was unable to process the contained instructions.

---

[API](https://skmtc.net/finix/apis/finix-api-reference.md) · [All operations](https://skmtc.net/finix/apis/finix-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/finix/finix-api-reference/versions/5426f6f99c52/schema)