Webhook Subscriptions

Manage webhook subscriptions to receive real-time notifications when events occur in Consignly.

Endpoints Overview

Create Webhook Subscription

Create a new webhook subscription to receive event notifications.

Endpoint: POST /v1/webhook-subscriptions/create

Request Body

{
  "webhookUrl": "https://your-app.com/webhooks/consignly",
  "eventType": 101,
  "signingKey1": "your-signing-key",
  "signingKey2": null,
  "clientPartnerId": "550e8400-e29b-41d4-a716-446655449801",
  "carrierPartnerId": null
}

Event Types

System Events:

Consignment Events (100s):

Schedule Events (200s):

Job Events (300s):

Request Example

curl -X POST "https://api.consignlyhq.com/v1/webhook-subscriptions/create" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-app.com/webhooks/consignly",
    "eventType": 101,
    "signingKey1": "your-signing-key"
  }'

Response Example

Status: 202 Accepted

{
  "webhookSubscriptionId": "550e8400-e29b-41d4-a716-446655447000"
}

Test Webhook Subscription

Send a test event to verify your webhook endpoint is working.

Endpoint: PUT /v1/webhook-subscriptions/{webhookSubscriptionId}/test

Path Parameters

Request Example

curl -X PUT "https://api.consignlyhq.com/v1/webhook-subscriptions/550e8400-e29b-41d4-a716-446655447000/test" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response

Status: 200 OK

A test event will be sent to your webhook URL.

Delete Webhook Subscription

Remove a webhook subscription.

Endpoint: DELETE /v1/webhook-subscriptions/{webhookSubscriptionId}/delete

Path Parameters

Request Example

curl -X DELETE "https://api.consignlyhq.com/v1/webhook-subscriptions/550e8400-e29b-41d4-a716-446655447000/delete" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response

Status: 200 OK

Webhook Payload Format

When an event occurs, Consignly sends a POST request to your webhook URL:

{
  "id": "evt_550e8400e29b41d4a716446655447100",
  "type": "consignment.created",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "consignmentId": "550e8400-e29b-41d4-a716-446655447200",
    "consignmentNumber": "CON-2024-001234",
    "clientId": "550e8400-e29b-41d4-a716-446655447201",
    "status": 1
  },
  "operationId": "EKm9H7omU69Aq5CYOebq1bjVqCDH7p-2T57Ce5X1MqPg9WdlBDzV90iJmKURkpHE2g"
}

Payload Fields

Verifying Webhook Signatures

Consignly signs all webhook payloads using SHA256-HMAC with your client secret as the key.

Signature Header

X-Consignly-Signature: sha256=abc123def456...

The signature is computed over the raw JSON body of the webhook payload.

Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, clientSecret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', clientSecret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhooks/consignly', (req, res) => {
  const signature = req.headers['x-consignly-signature'];
  const rawBody = req.rawBody; // Use raw body, not parsed JSON

  if (!verifyWebhookSignature(rawBody, signature, process.env.CLIENT_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook...
  res.status(200).send('OK');
});

Important: Use your client secret (from your custom app configuration) as the HMAC key, not a separate webhook secret.

Acknowledging Webhook Events

For export webhooks, acknowledge successful processing using the connection result endpoint:

curl -X PUT "https://api.consignlyhq.com/v1/consignments/{consignmentId}/connection-result" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "EKm9H7omU69Aq5CYOebq1bjVqCDH7p-2T57Ce5X1MqPg9WdlBDzV90iJmKURkpHE2g",
    "result": 1
  }'

Result Values

Best Practices

Endpoint Requirements

• Use HTTPS (required)
• Respond within 30 seconds
• Return 2xx status for success
• Implement idempotency (events may be retried)

Error Handling

• Log all webhook payloads for debugging
• Return appropriate HTTP status codes
• Implement retry logic for downstream failures

Security

• Always verify webhook signatures using your client secret
• Respond with 2xx status quickly, then process asynchronously if needed
• Log webhook payloads for debugging and audit purposes

Retry Policy

Failed webhook deliveries are retried with exponential backoff. A delivery is considered failed if:

• The endpoint returns a non-2xx HTTP status code
• The request times out
• The endpoint is unreachable

After 5 failed attempts, the webhook subscription is marked as failed and no further deliveries are attempted. You will need to fix the endpoint issue and reactivate or recreate the subscription.

Related Endpoints

• Consignments - Acknowledge export webhooks via connection-result