Velourcity
Back to Docs

Webhooks Integration

Receive real-time notifications about delivery events in your application. Webhooks ensure your systems stay synchronized with delivery status changes.

Real-time • Secure • Reliable
How Webhooks Work

Understand the webhook flow and delivery mechanism

1

Event Occurs

Delivery status changes or order events happen

2

Webhook Sent

We send a POST request to your endpoint

3

Your App Updates

Process the event and update your systems

Event Types

All available webhook events and their triggers

order.created

Sent when a new order is successfully created in the system.

Order Events
order.driver_assigned

Triggered when a driver accepts the order and begins heading to pickup.

Order Events
order.picked_up

Sent when the driver successfully picks up the order from the restaurant.

Delivery Events
order.delivered

Triggered when the order is successfully delivered to the customer.

Delivery Events
order.cancelled

Sent when an order is cancelled by the customer, restaurant, or system.

Order Events
payment.completed

Triggered when payment processing is completed successfully.

Payment Events
Webhook Payload Structure

Standard format for all webhook events

Example: Order Created Event

HTTP Headers

POST /your-webhook-endpoint HTTP/1.1
Host: yourapp.com
Content-Type: application/json
User-Agent: Velourcity-Webhooks/1.0
X-Velourcity-Signature: sha256=abc123...
X-Velourcity-Event: order.created
X-Velourcity-Delivery-Attempt: 1
Implementation Examples

Code examples for handling webhooks in different languages

Node.js / Express
Security & Best Practices

✅ Security Best Practices

  • • Always verify webhook signatures
  • • Use HTTPS endpoints only
  • • Implement idempotency handling
  • • Log all webhook events
  • • Handle duplicate deliveries

📋 Implementation Tips

  • • Return 200 status for successful processing
  • • Process webhooks asynchronously
  • • Implement retry logic for failures
  • • Set reasonable timeout values
  • • Monitor webhook delivery rates
Testing Webhooks

Tools and methods for testing webhook integration

Local Development

Use ngrok to expose your local server:

# Install ngrok
npm install -g ngrok

# Expose local port
ngrok http 3000

# Use the https URL as your webhook endpoint
https://abc123.ngrok.io/webhooks

Testing Tools

  • • Webhook.site - Online webhook testing
  • • Postman - API testing and mocking
  • • Developer Dashboard - Webhook logs and retry
  • • Unit Tests - Automated webhook testing

Ready to set up webhooks?

Get your API credentials and configure webhook endpoints in your developer dashboard.

Setup Webhooks