Webhook Subscriptions

Overview

Webhooks are automated notifications generated by system events that occur in your organization. You can create a webhook subscription and designate a URL to receive notifications when a Tink transaction status updates. By setting up automatic webhook notifications, you do not need to send check status requests to monitor sale status. Before you send a request, complete the prerequisites in Get Started with Tink Pay by Bank, including your merchant ID and REST API security key.

Notifications that contain sensitive, personally identifiable information (PII), such as account numbers, are sent using message-level encryption.

Transport Layer Security (TLS) is required to ensure data integrity.

Endpoints

POST /notification-subscriptions/v2/webhooks

See Endpoints for the full per-brand Server URLs reference.

Example

{  "name": "My Custom Webhook",  "description": "Sample Webhook from Developer Center",  "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>",  "products": [    {      "productId": "alternativePaymentMethods",      "eventTypes": [        "payments.payments.updated"      ]    }  ],  "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient",  "securityPolicy": {    "securityType": "KEY"  }}

{  "organizationId": "organizationId",  "productId": "terminalManagement",  "eventTypes": [    "terminalManagement.assignment.update"  ],  "webhookId": "ddb9bced-c3e3-1b1d-e053-9c588e0a3c42",  "name": "My Custom Webhook",  "webhookUrl": "https://MyWebhookServer.com:443/simulateClient",  "healthCheckUrl": "https://MyWebhookServer.com:443/simulateClientHealthCheck",  "createdOn": "2022-04-28T15:39:56.928Z",  "status": "ACTIVE",  "description": "Sample Webhook from Developer Center",  "retryPolicy": {    "algorithm": "ARITHMETIC",    "firstRetry": "1",    "interval": "1",    "numberOfRetries": "3",    "deactivateFlag": "false",    "repeatSequenceCount": "0",    "repeatSequenceWaitTime": "0"  },  "securityPolicy": {    "securityType": "KEY",    "digitalSignatureEnabled": "yes"  },  "version": "3",  "notificationScope": "SELF"}

Test Your Webhook Requests

You can send webhook related test requests. See the Create a Webhook section in the REST API Reference.

Field	Type	Description
`description`
`name`
`organizationId`
`products.eventTypes`		Set the value of this field to `payments.payments.updated`.
`products.productId`		Set the value of this field to `alternativePaymentMethods`.
`securityPolicy.securityType`		Set to `KEY` (mutual trust security type, default), `oAuth` (OAuth security type), or `oAuth_JWT` (OAuth with JSON Web Token (JWT) security type).
`webhookUrl`

Include these fields in addition to the Required Fields when using the OAuth security policy.

Required Fields for OAuth

Field	Type	Description
`securityPolicy.config.oAuthTokenExpiry`		Set to `365`.
`securityPolicy.config.oAuthTokenType`		Set to `Bearer`.
`securityPolicy.config.oAuthURL`

Include these fields in addition to the Required Fields and Required Fields for OAuth when using the OAuth with JWT security policy.

Required Fields for OAuth with JWT

Field	Type	Description
`securityPolicy.config.additionalConfig.aud`
`securityPolicy.config.additionalConfig.client_id`
`securityPolicy.config.additionalConfig.keyId`
`securityPolicy.config.additionalConfig.scope`

Optional Fields

Field	Type	Description
`deactivateflag`		Required if the `healthCheckUrl` field is present. Set to `true` to automatically activate the subscription.
`healthCheckUrl`		Set to the health check URL, which is required to auto-activate the subscription. If you do not include this field, the created subscription is inactive. An inactive subscription does not send notifications.
`retryPolicy.deactivateFlag`
`retryPolicy.firstRetry`
`retryPolicy.interval`
`retryPolicy.numberOfRetries`
`retryPolicy.repeatSequenceCount`
`retryPolicy.repeatSequenceWaitTime`

Notification Statuses

Webhook subscriptions send these notification statuses:

CANCELLED: The customer did not complete the checkout using the redirect URL.
FAILED: The sale request failed.
SETTLE_INITIATED: The customer completed checkout and Tink Pay by Bank is processing the sale.
SETTLED: The sale is settled for the requested amount.

Was this page helpful?

Last published: September 29, 2026