Best Practices

Build a robust integration by following these patterns.

Use a Queue

VectorCare sends webhooks in real-time, which means:

• Multiple webhooks can arrive in rapid succession
• A single transport may generate 10+ webhooks over its lifecycle
• Bursts of activity (shift changes, batch updates) create spikes

Don’t process webhooks synchronously. Instead:

1. Receive the webhook
2. Verify the signature
3. Push to your queue
4. Return 200 immediately
5. Process from the queue asynchronously

This ensures fast responses (our fastest integrators respond in under 1 second), absorbs traffic spikes, and lets you retry failed processing without losing data.

Prevent Duplicates and Handle Ordering

Webhooks can arrive out of order, and VectorCare may retry failed deliveries. Use timestamp-based upserts to handle both:

CREATE TABLE service_requests (
    id SERIAL PRIMARY KEY,
    external_id VARCHAR(50) UNIQUE NOT NULL,  -- service_request_id
    last_updated TIMESTAMP NOT NULL,
    data JSONB
);

-- Only apply updates when event_timestamp is newer
INSERT INTO service_requests (external_id, last_updated, data)
VALUES ('KP-ABCD1234', '2025-01-15T14:30:00Z', '...')
ON CONFLICT (external_id) DO UPDATE
SET last_updated = EXCLUDED.last_updated,
    data = EXCLUDED.data
WHERE service_requests.last_updated < EXCLUDED.last_updated;

Don’t rely on application-level checks before inserting. This leads to race conditions when processing concurrent webhooks.

Tip

Each webhook contains the complete current state. If you process a newer event first, you can safely skip older ones.

Handle Errors Gracefully

When sending state or location updates to VectorCare, handle failures appropriately:

Timestamp validation: Timestamps must be within 7 days of the current time and cannot be in the future. If a state update is rejected for timestamp reasons, don’t retry indefinitely - the timestamp will only get more stale.

Rate limiting: If you receive a 429 response, back off before retrying. Implement exponential backoff to avoid making the problem worse.

Network failures: Queue failed requests for retry, but set a reasonable limit. A state update from 3 days ago may no longer be relevant.

Don’t block on failures: If a state update fails, continue processing other requests. One problematic request shouldn’t halt your entire integration.

See Error Codes for the complete list of error responses.

Debug with Webhook History

VectorCare maintains a log of all webhook deliveries in the admin interface. Use this to:

• Verify webhooks are being sent
• Check delivery status and response codes
• Resend failed webhooks manually
• Inspect payload contents

If you suspect missing data, check the webhook history before assuming a bug in your integration.