Skip to main content
POST
/
webhook
/
ping
Test Webhook
curl --request POST \
  --url https://api.uip.digital/v1/webhook/ping \
  --header 'Authorization: Bearer <token>'
"HTTP/1.1 200 OK"
Test your webhook endpoint configuration before committing to production. This endpoint sends a test notification to verify that your webhook URL is properly configured and can receive UIP events. Use this during development to ensure your webhook handler is working correctly and can properly validate HMAC signatures.

​
Request

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer token with your API key: Bearer YOUR_API_KEY

​
Body Parameters

This endpoint requires no body parameters. It will automatically send a test webhook to the webhook URL configured in your Business Dashboard.

​
Response

​
Success Response (200 OK)

Returns HTTP status code 200 with no response body when the test webhook is successfully sent to your configured webhook URL.

​
Example Request

curl -X POST https://api.uip.digital/v1/webhook/ping \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example Response

HTTP/1.1 200 OK
No response body is returned on success.

​
Test Webhook Payload

When you call this endpoint, UIP sends a test notification to your configured webhook URL with the following structure: 
{
  "event": "test",
  "data": {
    "pong": "Pong"
  }
}
Headers sent to your webhook:
  • Content-Type: application/json
  • X-UIP-Signature: <hmac_sha256_signature> - HMAC SHA-256 signature for verification

​
Webhook Signature Verification

All webhook requests include an X-UIP-Signature header containing an HMAC SHA-256 signature. Your webhook handler must verify this signature to ensure requests are from UIP. 
const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-uip-signature'];
  const webhookSecret = 'YOUR_WEBHOOK_SECRET'; // From Business Dashboard

  // Calculate expected signature
  const hmac = crypto.createHmac('sha256', webhookSecret);
  hmac.update(JSON.stringify(req.body));
  const expectedSignature = hmac.digest('hex');

  // Verify signature
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  // Handle webhook event
  const { event, data } = req.body;

  if (event === 'test') {
    console.log('Test webhook received:', data.pong);
    return res.status(200).send('OK');
  }

  // Handle other events (identify, sign, message)

  res.status(200).send('OK');
});

​
Errors

See the Error Handling Guide for comprehensive error handling strategies. Possible error codes for this endpoint: Authentication Errors:
  • auth/missing-api-key - No API key provided in Authorization header
  • auth/invalid-api-key - Invalid API key
  • auth/revoked-api-key - API key has been revoked
  • auth/business-archived - Business account has been archived
Request Validation Errors:
  • request/webhook-missing - Webhook URL not configured in Business Dashboard
  • request/webhook-unreachable - Webhook URL is not accessible or did not return 200 status code
  • request/not-found - No such registered route in API service
Resource Errors:
  • resource/not-found - Business not found
Internal Errors:
  • internal/server-error - Failed to send test webhook or process request
  • data/corrupt - Webhook URL is malformed (must start with https://)

​
Implementation Flow

1

Configure Webhook URL

Add your webhook endpoint URL in the Business Dashboard. Must use HTTPS for production.
2

Implement Webhook Handler

Create an endpoint that accepts POST requests and verifies HMAC signatures
3

Test Webhook Configuration

Call the /webhook/ping endpoint to verify your webhook is reachable and working correctly
4

Verify Signature

Ensure your webhook handler correctly validates the X-UIP-Signature header
5

Return 200 Status

Your webhook must return HTTP 200 status code to acknowledge receipt

​
Best Practices

Always Verify Signatures

Validate the X-UIP-Signature header on every webhook request to prevent spoofing

Use HTTPS in Production

Webhook URLs must use HTTPS. HTTP is not allowed for security reasons.

Return 200 Quickly

Process webhooks asynchronously and return 200 immediately to avoid timeouts

Test Before Production

Use this endpoint during development to verify your webhook configuration works correctly

​
Common Issues

Problem: Test fails with request/webhook-unreachable errorCauses:
  • Webhook URL is not publicly accessible
  • Firewall blocking UIP servers
  • Webhook handler not returning 200 status code
  • HTTPS certificate issues
Solutions:
  • Verify webhook URL is publicly accessible
  • Check firewall rules allow UIP IP addresses
  • Ensure webhook returns 200 status for test events
  • Use valid HTTPS certificate
Problem: Webhook receives requests but signature validation failsCauses:
  • Using wrong webhook secret
  • Calculating signature on modified body
  • Character encoding issues
Solutions:
  • Get webhook secret from Business Dashboard
  • Calculate signature on raw request body (before parsing)
  • Use UTF-8 encoding for all strings
Problem: Test fails with request/webhook-missing errorCauses:
  • No webhook URL configured in Business Dashboard
  • Webhook URL field is empty
Solutions:
  • Log into Business Dashboard
  • Navigate to webhook settings
  • Add your webhook endpoint URL
Problem: Test fails with data/corrupt errorCauses:
  • Webhook URL does not start with https://
  • Invalid URL format
Solutions:
  • Ensure URL starts with https://
  • Use valid URL format: https://yourdomain.com/webhook

Webhooks Guide

Learn about webhook events and best practices

Identify API

Authentication endpoint with webhook events

Sign API

Signature endpoint with webhook events

Message API

Messaging endpoint with webhook events

Authorizations

​
Authorization
string
header
required

Use your UIP API key as a bearer token

Response

200 - text/plain

Webhook test sent successfully. Returns HTTP 200 OK status with no response body.