Webhooks

Real-time Webhook Integration

Receive webhook events from any external service. Process SMS, email, payment notifications, and custom events in real-time with our universal webhook receiver.

What are Webhooks?

Webhooks are automated messages sent from one application to another when a specific event occurs. Unlike traditional APIs where you poll for updates, webhooks push data to your application instantly when something happens.

Real-time Updates

Get notified instantly when events occur

No Polling Required

Eliminates the need for constant API checks

Automated Workflows

Trigger automated processes and integrations

How Webhooks Work

1
Event occurs (SMS received, email arrives)
Ringslack processes the event
2
HTTP POST request sent to your endpoint
Your application receives the webhook
3
Your app processes the data

General Webhooks

Receive any webhook events from external services

Endpoint
/api/webhooks
Provider
Any Service
Setup Location
API Settings > Webhooks
Setup Guide

SMS Webhooks

Receive incoming SMS messages in real-time

Endpoint
/api/webhooks
Provider
Twilio
Setup Location
SMS Settings > Webhooks
Setup Guide

Email Webhooks

Receive incoming emails instantly

Endpoint
/api/webhooks
Provider
Mailcow
Setup Location
Email Settings > Webhooks
Setup Guide

Setup Guide

1

Create a Webhook Endpoint

Create an endpoint in your application that can receive HTTP POST requests. This endpoint should:

  • Accept POST requests
  • Return a 200 OK response quickly
  • Process the webhook data asynchronously if needed
  • Validate the webhook payload (recommended)

Example Node.js Endpoint

app.post('/webhooks/sms', (req, res) => {
  // Process webhook data
  console.log('SMS received:', req.body);

  // Return success response
  res.status(200).json({ received: true });
});
2

Configure Webhook URLs

Set up the webhook URLs in your service provider's dashboard:

Twilio SMS Webhook

In your Twilio Console, go to Phone Numbers → Manage → Active Numbers

https://yourdomain.com/api/webhooks
Mailcow Email Webhook

In Mailcow admin panel, configure webhook settings

https://yourdomain.com/api/webhooks
3

Test Your Webhook

Send a test message to verify your webhook is working correctly.

Test SMS Webhook

curl -X POST https://yourdomain.com/api/webhooks \
   -H "x-tenant-id: YOUR_TENANT_ID" \
   -H "x-customer-id: YOUR_CUSTOMER_ID" \
   -H "x-webhook-event: test" \
   -H "Content-Type: application/json" \
   -d '{
     "message": "Test webhook payload",
     "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"
   }'

Webhook Payload Examples

SMS Webhook Payload

Received when an SMS message arrives at your Twilio number.

{
  "From": "+1234567890",
  "To": "+0987654321",
  "Body": "Hello, this is a test message!",
  "MessageSid": "SM1234567890abcdef",
  "AccountSid": "AC1234567890abcdef",
  "FromCity": "New York",
  "FromState": "NY",
  "FromZip": "10001",
  "FromCountry": "US",
  "ToCity": "Los Angeles",
  "ToState": "CA",
  "ToZip": "90210",
  "ToCountry": "US",
  "SmsMessageSid": "SM1234567890abcdef",
  "NumMedia": "0",
  "NumSegments": "1"
}

Email Webhook Payload

Received when an email arrives in your Mailcow mailbox.

{
  "from": "sender@example.com",
  "to": ["recipient@yourdomain.com"],
  "cc": [],
  "bcc": [],
  "subject": "Important Update",
  "text": "This is the plain text version of the email.",
  "html": "<p>This is the <strong>HTML</strong> version of the email.</p>",
  "messageId": "msg_1234567890@example.com",
  "date": "2024-01-15T10:30:00Z",
  "attachments": [],
  "mailbox": "inbox",
  "size": 1024,
  "priority": "normal"
}

Security & Best Practices

Security Recommendations

Validate Webhook Signatures

Verify that webhooks are genuinely from Ringslack using signature validation.

Use HTTPS Endpoints

Always use HTTPS URLs for webhook endpoints to encrypt data in transit.

Log Webhook Activity

Keep logs of webhook deliveries for debugging and audit purposes.

Performance Tips

Respond Quickly

Return HTTP 200 within 5 seconds to avoid timeout issues.

Handle Retries

Design your endpoint to handle duplicate webhook deliveries gracefully.

Process Asynchronously

Process webhook data in background jobs to avoid blocking responses.

Testing & Debugging

Webhook Testing Tools

Webhook.site

Free online tool to inspect webhook payloads without coding.

webhook.site
ngrok

Expose local development servers to the internet for testing.

ngrok.com
RequestBin

Create temporary endpoints to capture and inspect HTTP requests.

requestbin.com

Common Issues & Solutions

Webhook Not Receiving
  • • Check if URL is publicly accessible
  • • Verify HTTPS is being used
  • • Ensure endpoint returns 200 OK
Duplicate Webhooks
  • • Use message IDs to prevent duplicates
  • • Implement idempotent processing
  • • Check for retry headers
Timeout Issues
  • • Respond within 5 seconds
  • • Process data asynchronously
  • • Use background job queues

Ready to Automate?

Start receiving real-time notifications from any service and build powerful automated workflows with Ringslack webhooks. Process events instantly and scale your integrations.