Sign in

v1

latestOpenAPI 3.0.22026-08-061303782.1 MB
Webhooks

Create a Webhook

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.

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 for supported entities and event types.

post/webhooks

Headers

Finix-Versionstring
Example:2022-02-01

Specify the API version of your request. For more details, see Versioning.

Content-Typestring
Example:application/json

The data type being sent in the request body must be application/json.

Request body

OR
OR
OR
OR

Example request

{
  "enabled_events": [
    {
      "entity": "transfer",
      "types": [
        "created"
      ]
    }
  ],
  "url": "https://httpbin.org/post"
}

Response

A single Webhook

idstring

The ID of the resource.

created_atstring date-time

Timestamp of when the object was created.

updated_atstring date-time

Timestamp of when the object was last updated.

applicationstring

ID of the Application the resource was created under.

enabledboolean

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.
is_accepting_eventsboolean

Whether the Webhook is currently accepting events; this field mirrors the enabled field.

nicknamestring

A human-readable name for the Webhook.

previous_secret_expires_atstring nullable

The time when the previous secret_signing_key expires. Set when the signing key is rotated; null on initial creation.

secret_signing_keystring 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.

urlstring

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.

Example response

{
  "enabled_events": [
    {
      "entity": "transfer",
      "types": [
        "created"
      ]
    }
  ]
}