Connected account webhooks

Through the Integration Partner Program, we're making it easy to access the API tokens for the connected accounts of merchants you refer to us!

When a merchant signs up with Helcim through your partner referral link, they will become a connected account. We'll automatically create the API Access Configuration required for you to process payments on their behalf through your integration with the Helcim V2 API or HelcimPay.js.

We'll send you a webhook event to your deliver URL with that referred merchants connectedAccountId and their api-token so that you can store these securely in your system to process future payments.

Webhook events

Webhooks are available for merchant approval events for Helcim partners who wish to be notified when their referred merchant has signed up and been approved for Helcim's services.

A connectedAccount webhook event will be sent to the deliver URL that was provided during your onboarding with our Partnerships team. The event will contain:

• The automatically generated apiToken of a single connected account
• The connectedAccountId
• The outcome of the risk review for the connected account

The API token must be sent in the header of all requests to Helcim for that connected account, as the value for the api-token parameter, in order for payments to be correctly attributed and deposited to that merchant.

Webhook events will be triggered for all events of the selected type when:

• You have subscribed to webhooks.
• A connected account has signed up for Helcim's services and have been approved by Helcim's risk team.

📘

Connected account webhooks will only trigger for the auto generated API token and any subsequent API tokens created by the merchant will not trigger this webhook event.

// Example webhook event request headers and payload

// headers
webhook-signature:v1,CsvqmJB7fuYUFyusd98s7f67s89fGFSf8slsld=
webook-timestamp:1716412291
webhook-id:msg_67sdf768sfjklLHSIyopUsiKFdfsyuP

// payload
{
  "apiToken": "87S6gojkd98lhh2h23f2vqmJ",
  "event": "approved",
  "connectedAccountId" : "abc-123_def-456"
}

Deliver URL

Helcim webhooks will send a POST request to an https URL that you have set up and shared with Helcim to be the delivery endpoint for webhook events. Please ensure this https URL is set up with the ability to accept POST requests with a JSON request payload.

The endpoint that you share with Helcim will be used by us to share application and approval data with you, upon registration and approval in Helcim's systems.

The endpoint will need to be able to handle different events sent to it, with each event being identified in the request payload.

🚧

It's important to disable CSRF protection for this endpoint, if the framework you use has it enabled by default.

Another important aspect of handling webhook events is to verify the signature when processing them so you can be certain that the request payload is from a trusted source. You can learn more about this in the Verifying Webhook Events section below.

Verifying a webhook event

Helcim uses an HMAC (hash-based message authentication codes) with SHA-256 encryption to sign its webhooks. To protect your server from unauthorized webhook events, we strongly recommend that you use HMAC to verify the authenticity of the data sent to your webhook URL by using the Webhook Verifier Token that Helcim will provide to you.

Each webhook event will be delivered with a signature in the header of the request (the header key is webhook-signature). The unique Verifier Token that you received during onboarding can be used in combination with the event payload to generate a signature. If the generated signature and the signature in the request header match, then you can be confident that the webhook event came from Helcim and is safe to use.

During onboarding with Helcim's Integration Partner Program, you will receive the Verified Token that should be used for verifying the webhook event data. This will be sent through 1Password to an email address you provide and the link will expire in 24 hours. Please keep this key in a safe location.

How to verify

To verify the webhook event data, use the following steps:

1. Generate the verification payload. This is a combination of the webhook event ID (from the request header webhook-id), the webhook timestamp (from the request header webhook-timestamp), and the request body. These 3 pieces of data need to be joined together using a period.

// The verification payload is gererated by concatenating the
// webhook ID from the request header, timestamp from the request header,
// and the request payload, separated by the full-stop character (.)
const verification_payload = `${webhook_id}.${webhook_timestamp}.${request_body}`

2. Generate the verification signature by using the SHA-256 algorithm, the Verifier Token as the HMAC signing key, and the verification payload from the previous step. Once generated, base64 encode the generated verification signature in preparation for the next step.
3. Compare the webhook signature in the request header with the base64 encoded generated verification signature from the previous step. If they match, the request came from Helcim and you can use the request payload as needed. If they do not match, you should reject the request as it was from an unauthorized source or has been modified in transit.

const crypto = require('crypto');

// webook signatures from the header of the request, including the
// corresponding version identifier
let webhook_signature = "v1,CsvqmJB7fuYUFyusd98s7f67s89fGFSf8slsld=";

// webhook timestamp from the header of the request
const webook_timestamp = "1716412291";

// webhook ID from the header of the request
const webhook_id = "msg_67sdf768sfjklLHSIyopUsiKFdfsyuP";

// The verification payload is gererated by concatenating the
// webhook ID from the request header, timestamp from the request header,
// and the request payload, separated by the full-stop character (.)
const verification_payload = `${webhook_id}.${webhook_timestamp}.${request_body}`;

// Verifier Token provided during onboarding
const signing_key = "CHANGE_ME";

// This generated signature should match the one sent in the
// webhook-signature header.
const generated_verification_signature = crypto
    .createHmac('sha256', signing_key)
    .update(verification_payload)
    .digest('base64');

// check if the generated signature matches the signature in the request
if webhook_signature != generated_verification_signature) {
    // reject the request
} else {
    // accept the request, store data as needed
}

Confirming receipt of a webhook event

If the webhook event was accepted, you should respond to the HTTP request with a 2xx status code within 15 seconds of receiving the request.

Accessing your Verifier Token

The Helcim team will send you an email using 1Password that contains your Verifier Token. This key is used in the webhook verification process and should be stored in your system securely to be accessed when completing your webhook verification.

To access the key, please enter your email address when you have received the request within 24 hours. After this time period the link will expire and you will need to request a new link from your Partnership specialist.

Webhook event schedule

A failed webhook event is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

• Immediately
• 5 seconds
• 5 minutes
• 30 minutes
• 2 hours
• 5 hours
• 10 hours
• 10 hours (in addition to the previous)

For example, an event that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.