Webhooks allow your application to receive real-time notifications from the K-LINK Customer Support Platform. When specific events occur in your system, we'll send an HTTP POST request to your endpoint with event data.Getting Started#
Step 1: Create an Application#
1.
Navigate to Settings → Developer Tools
2.
Click the Create App button
3.
Enter your application details and select the appropriate environment (Development or Production)
Webhook Configuration#
Setting Up Webhooks#
1.
Go to your application's Manage settings
2.
Scroll to the Webhook Signature section
Event Notification Endpoint URL#
Provide a URL where you want to receive webhook notifications. This endpoint must be publicly accessible and accept HTTP POST requests.Choose your preferred authentication method for webhook requests:Default by K-LINK (Recommended): Uses HMAC-SHA256 signature verification
Basic Authentication: Standard HTTP Basic Auth
Custom Header: Provide your own custom authentication header
Webhook Signature#
For enhanced security, we use HMAC-SHA256 signatures to verify that webhook requests are coming from K-LINK.Signature Secret#
A signature secret is generated for your application. This secret is included in the authorization header of incoming webhook requests and is signed with your Signature secret.Signature Method: HMAC-SHA256 signatureVerifying Webhook Signatures (Recommended for security)#
When you receive a webhook request, verify the signature by:1.
Extract the signature from the request header
2.
Use your signature secret to compute the expected HMAC-SHA256 hash
3.
Compare the computed hash with the provided signature
4.
Only process the request if signatures match
Event Subscriptions#
Event subscriptions allow you to choose which events trigger webhook notifications to your endpoint.Available Events#
Manage events related to contact creation and updates in your system:All events: Subscribe to all contact-related events
New Contact Created: Triggered when a new contact is added to your system
Contact Updated: Triggered when a contact's information is modified
Message Events#
Track events for conversation messages between your application and customers:All events: Subscribe to all message-related events
Inbound Message Received: Triggered when a new message is received from a customer
Outbound Message Sent: Triggered when a message is sent to a customer
Configuring Event Subscriptions#
1.
In the Event Subscriptions section, enter a Subscription name
2.
Under Events, select which events you want to subscribe to
3.
Configure your Event notification endpoint URL
4.
Choose your preferred Authentication Header Option
5.
Click Save to activate the subscription
Affected resource data (contact or message details)
Event metadata and context
Response Expected#
Your webhook endpoint should respond with an HTTP 2xx status code to confirm successful receipt. If we don't receive a 2xx response, we may retry the request.Best Practices#
1.
Validate Signatures: Always verify webhook signatures before processing
2.
Idempotency: Handle duplicate webhook deliveries gracefully
3.
Async Processing: Process webhooks asynchronously to avoid timeout issues
4.
Logging: Log all webhook requests for debugging and monitoring
5.
Security: Keep your Client Secret and Signature secret confidential
6.
Timeouts: Ensure your webhook endpoint responds quickly (within 10 seconds)
Testing#
You can test your webhook setup by:1.
Creating test contacts or messages in your K-LINK dashboard
2.
Monitoring your webhook endpoint logs for incoming requests
3.
Verifying that signatures are being validated correctly
Regenerating Secrets#
If you suspect your secrets have been compromised:1.
Navigate to your application's Manage settings
2.
Click Regenerate next to the Client Secret or Signature secret
3.
Update your application code with the new secrets
4.
Test to ensure webhooks are still being received
Danger Zone#
⚠️ Warning: Actions in this section cannot be undone.Delete App: Deletes the application entirely. All access tokens will be revoked and webhooks will cease to function.
Error Handling#
If the client endpoint does not return a 200 response code for a request call, klink.cloud will consider it as an error. If the number of errors exceeds 50 per 1 hour, the webhook endpoint will be deactivated.Ensure our IP addresses (51.79.216.180) are not blocked.
Retry Mechanism#
If a webhook request does not yield a 200 response code within 10 seconds, it will try again. Three retries are attempted at intervals of 30 seconds, 60 seconds, and 90 seconds, respectively, until a 200 response code is received.Singature Validation#
The Normalization Process
To ensure signature consistency, the code performs specific formatting before hashing:Query Normalization: Keys are sorted alphabetically. If a key has multiple values, the values are sorted alphabetically.Format: key=[val1 val2]&key2=[val1] (Note: This uses Go's default slice formatting).JSON Normalization: The JSON body is recursively sorted by key. Nested objects are also sorted alphabetically to ensure a deterministic string representation.Payload Concatenation: The signature is generated from a raw string combined as: Method + URL + NormalizedQuery + NormalizedBody 
