Webhook Configuration and Delivery

This guide describes how the customer can configure webhook delivery for platform events using the public Webhook API. A webhook is an outbound notification sent by the Interlace platform to a customer-owned external URL when a subscribed business event occurs, such as a completed payment or a customer address change.

The customer configures one webhook record that contains both the subscribed event list and the delivery configuration. This includes the destination URL, authentication method, optional OAuth token settings, optional header information, optional JWE payload encryption, and version information.

Important Model Behavior

• Webhook configuration is created through one public endpoint: POST /webhooks.
• A webhook record defines both what events should trigger delivery and where the notification should be sent.
• The events field contains the subscribed event names. When one of those events occurs, the platform resolves the matching webhook configuration and invokes the configured url.
• The webhook id and createdTime are generated by the platform after the webhook record is created.
• headerInfo behavior depends on authType. For NONE, BASIC, and OAUTH, headerInfo is sent as webhook request headers. For OAUTHPOST, headerInfo values are sent as additional fields in the OAuth token request body.
• Payload encryption is optional. When enabled, the platform encrypts the webhook payload using the configured public key before sending it to the external endpoint.
• Webhook delivery supports configurable retries through a scheduled retry task. The default retry count is controlled by platform configuration, but it can be overridden through retry task parameters without changing the environment-level setting.

Access Flow

• The customer creates a webhook using POST /webhooks.
• The webhook record stores the subscribed event names and the delivery configuration.
• A business event occurs in the platform.
• The webhook service finds webhook records subscribed to that event.
• The webhook service reads the configured url, authType, headerInfo, and payload security settings.
• If OAuth is configured, the webhook service obtains an access token before invoking the webhook URL.
• If JWE is configured, the webhook payload is encrypted before delivery.
• The webhook service sends the notification to the configured customer URL.
• If delivery fails, the failure is recorded in the transmission log. A scheduled retry task can later pick up the failed transmission and retry delivery according to the configured retry policy.

Webhook Create API

Use the following API to create a webhook that subscribes to one or more events and configures how notifications should be delivered.

POST /webhooks

Example environment URL:
POST https://{HOST_NAME}.infinant.com/interlace/platform-api/v1/webhooks

Request Headers

Request and Response Model

The request body uses the WebhookSubscription model. The successful response returns the created Webhook record.

Response Codes

Required Configuration Values

WebhookSubscription Field Reference

Webhook Response Field Reference

Supported Endpoint Authentication

Webhook endpoint authentication is configured using authType. The supported values are BASIC, OAUTH, OAUTHPOST, and NONE.

Authentication Mode: NONE

No authentication is applied when invoking the external webhook endpoint. This option should only be used when the endpoint does not require authentication or when authentication is handled by another approved external mechanism.

{
  "authType": "NONE"
}

Authentication Mode: BASIC

The webhook service authenticates to the customer endpoint using Basic Authentication. The configured clientKey and clientSecret are used as the credential values.

{
  "authType": "BASIC",
  "clientKey": "webhook-user",
  "clientSecret": "webhook-password"
}

Authentication Mode: OAUTH

The webhook service obtains an OAuth Bearer token before invoking the customer endpoint. The configured tokenURL, clientKey, and clientSecret are used to request the access token. The webhook request is then sent with Authorization: Bearer <access_token>.

{
  "authType": "OAUTH",
  "tokenURL": "https://auth.customer.com/oauth/token",
  "clientKey": "client-id",
  "clientSecret": "client-secret"
}

Authentication Mode: OAUTHPOST

The webhook service obtains an OAuth Bearer token using a POST-based token request. This option is used when the authorization server requires additional token request fields, such as audience or scope, to be included in the request body.

{
  "authType": "OAUTHPOST",
  "tokenURL": "https://auth.dev.customer.com/oauth/token",
  "clientKey": "client-id",
  "clientSecret": "client-secret",
  "headerInfo": "[{\"audience\":\"https://api.dev.customer.com\"},{\"scope\":\"infinant:send-payment-webhook\"}]"
}

headerInfo Handling

The headerInfo field is used to configure additional request information. Its behavior depends on authType.

Example headerInfo value for OAUTHPOST:

headerInfo = '[{"audience":"https://api.dev.customer.com"},{"scope":"infinant:send-payment-webhook"}]'

For OAUTHPOST, the above configuration adds the following fields to the OAuth token request body:

grant_type=client_credentials
audience=https://api.dev.customer.com
scope=infinant:send-payment-webhook

JWE Payload Encryption

The webhook model supports payload encryption using JWE. When enabled, the platform encrypts the webhook payload before sending it to the external endpoint. The customer receiving system must decrypt the payload using the corresponding private key.

{
  "payloadSecurity": "JWE",
  "payloadEncryptionAlg": "RSA-OAEP-256",
  "payloadEncryptionEnc": "A256GCM",
  "payloadEncryptionKeyId": "customer-key-001",
  "payloadEncryptionPublicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
}

Retry Handling and Delivery Resilience

The webhook service supports configurable retries when a customer endpoint is temporarily unavailable or when a webhook delivery attempt fails.

This capability improves delivery resilience because a temporary outage, network issue, timeout, or short-lived authentication problem does not immediately stop the delivery process. Instead, failed webhook transmissions can be picked up later by the retry process and delivered again based on the configured retry policy.

Webhook retries are handled by a scheduled retry batch task by the platform. This task periodically searches for failed transmission records and attempts to resend them, as long as the retry count has not exceeded the configured maximum.

Retry behavior is controlled by platform-level retry configuration.

The default value is: 3

However, this default value can be updated upon client’s request. Note that this is an environment setting i.e. all tenants in the given environment would be impacted by the change.

Retry Behavior

When a webhook delivery fails:

1. The failed delivery is recorded in a transmission log.
2. The retry task searches for failed transmission records.
3. The retry task selects eligible failed records based on the configured retry parameters.
4. The webhook delivery is attempted again.
5. The retry count is updated.
6. Once the configured retry maximum is reached, the delivery is no longer retried automatically.

This retries mechanism allows the platform to continue attempting webhook delivery during temporary customer endpoint outages, while still preventing unlimited retry attempts.

Failed Webhook Delivery Logs

The platform also provides a transmission log API that can be used to search webhook delivery records, including failed webhook delivery attempts.

This allows customers or support teams to review webhook delivery status, retry count, transmission details, and failure information.

Use the following API to search transmission logs:

GET /message/transmit/log

This API supports filters such as transmission type, status, date range, template, limit, and offset.

To review failed webhook deliveries, the request should filter the transmission logs using the webhook transmission type and the failed delivery status supported by the environment.

Example Request

curl --location --globoff 'https://api.sandbox.infinant.com/interlace/notifications-api/v1/message/transmit/log?transmitType=WEBHOOK&status=FAILED&limit=50&offset=0' \
--header 'x-rquid: <REQUEST_ID>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response Model

The response contains a paginated list of transmission log records.

Important fields include:

Create Webhook

Use POST /webhooks to create the webhook configuration. The request contains the subscribed events, target URL, authentication
configuration, optional header information, optional JWE encryption settings, and version.

curl 'https://{HOST_NAME}.infinant.com/interlace/platform-api/v1/webhooks' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer <ACCESS_TOKEN>' \
  -H 'x-idempotency-key: <IDEMPOTENCY_KEY_UUID>' \
  -H 'x-rquid: <UNIQUE_RQ_UUID>' \
  --data-raw '<PAYLOAD_JSON>'

Request Example: No Authentication

{
  "name": "CustomerAddressWebhook",
  "description": "Endpoint used to receive customer address change notifications",
  "url": "https://api.customer.com/webhooks/customer-address",
  "authType": "NONE",
  "events": [
    {
      "name": "customer.address.changed"
    }
  ],
  "payloadSecurity": "NONE",
  "version": 1
}

Request Example: Basic Authentication with Additional Headers

{
  "name": "PaymentWebhookBasic",
  "description": "Endpoint used to receive payment notifications",
  "url": "https://api.customer.com/webhooks/payments",
  "authType": "BASIC",
  "clientKey": "webhook-user",
  "clientSecret": "webhook-password",
  "events": [
    {
      "name": "payment.completed"
    }
  ],
  "headerInfo": "[{\"X-Customer-Id\":\"customer-123\"},{\"X-Environment\":\"sandbox\"}]",
  "payloadSecurity": "NONE",
  "version": 1
}

Request Example: OAuth POST with Audience and Scope

{
  "name": "PaymentWebhookOAuthPost",
  "description": "Endpoint used to receive payment notifications using OAuth POST",
  "url": "https://api.customer.com/webhooks/payments",
  "authType": "OAUTHPOST",
  "tokenURL": "https://auth.dev.customer.com/oauth/token",
  "clientKey": "client-id",
  "clientSecret": "client-secret",
  "events": [
    {
      "name": "payment.completed"
    }
  ],
  "headerInfo": "[{\"audience\":\"https://api.dev.customer.com\"},{\"scope\":\"infinant:send-payment-webhook\"}]",
  "payloadSecurity": "NONE",
  "version": 1
}

Request Example: OAuth POST with JWE Payload Encryption

{
  "name": "SecurePaymentWebhook",
  "description": "Endpoint used to receive encrypted payment notifications",
  "url": "https://api.customer.com/webhooks/payments",
  "authType": "OAUTHPOST",
  "tokenURL": "https://auth.dev.customer.com/oauth/token",
  "clientKey": "client-id",
  "clientSecret": "client-secret",
  "events": [
    {
      "name": "payment.completed"
    }
  ],
  "headerInfo": "[{\"audience\":\"https://api.dev.customer.com\"},{\"scope\":\"infinant:send-payment-webhook\"}]",
  "payloadSecurity": "JWE",
  "payloadEncryptionAlg": "RSA-OAEP-256",
  "payloadEncryptionEnc": "A256GCM",
  "payloadEncryptionKeyId": "customer-key-001",
  "payloadEncryptionPublicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "version": 1
}

Sample Created Webhook Response

After the webhook is created, the platform returns the created Webhook record. The id and createdTime values are generated by the platform. The clientSecret value is secured and should not be expected to be returned in plain text.

{
  "id": "webhook-12345",
  "name": "SecurePaymentWebhook",
  "description": "Endpoint used to receive encrypted payment notifications",
  "url": "https://api.customer.com/webhooks/payments",
  "authType": "OAUTHPOST",
  "clientKey": "client-id",
  "tokenURL": "https://auth.dev.customer.com/oauth/token",
  "events": [
    {
      "name": "payment.completed"
    }
  ],
  "createdTime": "2026-07-15T13:54:42Z",
  "headerInfo": "[{\"audience\":\"https://api.dev.customer.com\"},{\"scope\":\"infinant:send-payment-webhook\"}]",
  "payloadSecurity": "JWE",
  "payloadEncryptionAlg": "RSA-OAEP-256",
  "payloadEncryptionEnc": "A256GCM",
  "payloadEncryptionKeyId": "customer-key-001"
}

Complete Runtime Example

A customer wants to receive a webhook notification whenever a payment is completed. The customer OAuth provider requires audience and scope during token generation, and the webhook payload must be encrypted using JWE.

Webhook Configuration

{
  "name": "CompletedPaymentWebhook",
  "description": "Receives completed payment webhook notifications",
  "url": "https://api.customer.com/webhooks/completed-payments",
  "authType": "OAUTHPOST",
  "tokenURL": "https://auth.dev.customer.com/oauth/token",
  "clientKey": "customer-client-id",
  "clientSecret": "customer-client-secret",
  "events": [
    {
      "name": "fedwire.payment.initiated "
    }
  ],
  "headerInfo": "[{\"audience\":\"https://api.dev.customer.com\"},{\"scope\":\"infinant:send-payment-webhook\"}]",
  "payloadSecurity": "JWE",
  "payloadEncryptionAlg": "RSA-OAEP-256",
  "payloadEncryptionEnc": "A256GCM",
  "payloadEncryptionKeyId": "payment-webhook-key-001",
  "payloadEncryptionPublicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "version": 1
}

Runtime Behavior

7. A payment.completed event occurs in the platform.
8. The webhook service finds webhook records subscribed to payment.completed in the events list.
9. The webhook service loads the matching webhook configuration named CompletedPaymentWebhook.
10. Because authType is OAUTHPOST, the webhook service requests an OAuth access token from the configured tokenURL.
11. The OAuth token request body includes grant_type=client_credentials, audience, and scope.
12. The webhook service encrypts the payload using the configured JWE public key.
13. The webhook service sends the encrypted webhook notification to the configured url using Authorization: Bearer <access_token>.
14. If the customer endpoint is temporarily unavailable, the webhook service can retry delivery according to the configured maximum retry count.

Customer Handling

• Use HTTPS for all webhook URLs.
• Avoid authType = NONE in production environments unless another approved security control is in place.
• Store clientSecret, client credentials, access tokens, private keys, and generated reports securely.
• Do not expose secrets, tokens, or private keys in browser-side code, logs, or public repositories.
• Use OAUTHPOST when the OAuth provider requires additional token request body fields such as audience or scope.
• Use JWE payload encryption when webhook payloads contain sensitive information.
• Protect the private key associated with the public key configured for JWE encryption.
• Ensure the receiving system can process the selected authentication method and payload security mode.
• Plan for temporary downtime by validating how the customer endpoint behaves when the platform retries webhook delivery.