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

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.

Is RTP Receive a separate webhook event?

No.

RTP Receive activity is delivered through Transaction Status Updated events.

There is not a standalone RTP Receive webhook event.

Topic-Level Example

Transfer Topic

Receive all Transfer events.

Event-Level Example

Transfer Topic

Receive RTP Settlement only.

Combination Example

Transfer Topic

Receive all Transfer events.

Transaction Topic

Receive Transaction Status Updated events only.

What is transfer_queued?

transfer_queued indicates that an RTP transfer has entered queue processing and has not yet reached a final outcome.

A queued transfer may subsequently result in:

• RTP Settlement
• Transfer Status Changed with a failed status

Clients should continue monitoring queued transfers until a final outcome is received.

What is queued_until?

The queued_until field indicates when queue processing is expected to complete.

Queued transfers may subsequently settle or fail after queue processing is completed.

Can queued transfers settle or fail?

No.

Queued transfers may subsequently:

• Settle successfully
• Fail

The final transfer outcome is delivered through subsequent transfer events.

How do I test queued transfers in Sandbox?

Use one of the following memo values when creating an Instant Payment transfer:

Successful Queue Scenario

queue_then_settle

How do I validate webhook authenticity?

Validate the following headers using the shared HMAC key provided during onboarding:

• X-Request-Signature-SHA-256
• X-Request-Signature-Timestamp

Refer to the Webhook Authentication documentation for the complete validation process.

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 34-hour period.

Retry 9 occurs approximately 17 hours after the original delivery attempt.

Retry 10 occurs approximately 34 hours after the original delivery attempt.

How do webhook retries work?

Webhook deliveries use exponential backoff when retrying failed requests.

A failed webhook delivery may be retried up to 10 times if a successful HTTP 2xx response is not received.

Retry Schedule

Important Notes

• Retry timing follows an exponential backoff pattern.
• Any HTTP 2xx response is considered a successful delivery and stops all remaining retry attempts.
• Newline supports up to 10 retry attempts per webhook notification.
• When 10 retries are configured, delivery attempts may continue for approximately 34 hours and 6 minutes after the initial delivery attempt.

What happens if my endpoint is unavailable?

If a webhook endpoint is unavailable or returns an HTTP 4xx or 5xx response, the delivery is considered unsuccessful and may be retried according to the configured retry schedule.

Clients should ensure webhook endpoints remain available and continue processing events until a successful HTTP 2xx response is returned.

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.