Webhooks FAQs

How are webhook URLs constructed?

Webhook endpoints follow a standardized format:

{base_url}/webhook/{topic-path}

Where:

• base_url is provided by the client
• /webhook is a required path segment
• topic-path is derived from the subscribed topic

Examples:

https://example.com/webhook/transfer
https://example.com/webhook/virtual-reference-number

How are webhook URLs constructed?

Webhook endpoints follow the standard format shown above. Newline appends the topic-specific path to the registered base URL.

What topic names should I use?

Use the supported webhook topics defined in the Webhook Topic documentation. Refer to the Webhook Topics page for the complete list of supported topics and topic definitions.

Can I customize the endpoint path?

You can define the base URL that Newline uses for webhook delivery. Newline appends the webhook topic path to the base URL. Topic paths are derived from the subscribed topic and cannot be customized.

Can I include an API key in my webhook URL?

Yes. An API key may be included as part of the registered base URL before the webhook topic path.

Example:

https://example.com/my-api-key/webhook/transfer

Can I append the API key after the topic path?

No. Appending an API key after the topic path is not currently supported.

Not supported:

https://example.com/webhook/transfers/my-api-key

Do webhook URLs include client or environment names?

No. Webhook endpoint paths are derived from the configured topic path and do not automatically include client names, tenant identifiers, or environment names.

Can I subscribe to individual webhook events?

Yes. Newline supports both topic-level and event-level webhook subscriptions.

Topic-level

Receive all events associated with a topic.

Event-level

Receive only selected events within a topic.

Combination

Mix topic-level and event-level subscriptions to support more granular event delivery requirements.

Webhook delivery routing is based on the configured topic endpoint path. The event_type field identifies the event contained within the payload but is not used to determine the delivery endpoint.

How are webhook events routed?

Webhook delivery routing is topic-based.

Events are delivered to the endpoint associated with the subscribed topic path. Event-level subscriptions do not create separate delivery endpoints.

For example:

https://example.com/webhook/transfer

May receive events such as:

• Transfer Initiated
• Transfer Status Changed
• RTP Settlement

Depending on the configured subscription.

The event_type field identifies the event contained in the payload, while the topic path determines the delivery endpoint.

How are failed webhook deliveries handled?

Webhook deliveries use exponential backoff when retrying failed requests.

A webhook notification may be retried up to 10 times over an approximate 24-hour period.

Successful Deliveries

Any HTTP 2xx response is considered a successful delivery.

Failed Deliveries

Any HTTP 4xx or 5xx response is considered a failed delivery and is eligible for retry according to the configured retry schedule.

Is a /health endpoint required?

No.

Newline supports optional health checks against a /health endpoint when one is available. Clients are not required to implement a /health endpoint to receive webhook deliveries.

If implemented, a health endpoint may be used for:

• Connectivity validation
• Operational monitoring
• Environment readiness checks

Are topic names customizable?

No.

Webhook topic names are defined by Newline and cannot be customized by clients. Newline uses the configured topic name to generate the topic-specific endpoint path used for webhook delivery.