Webhooks
Webhooks allow your application to receive real-time events from THEITBULLS. Instead of polling for updates, we send POST requests to your webhook URL when events occur.
Real-time events: Webhooks are delivered within seconds of the event occurring.
Configuring Webhooks
- Log in to your dashboard
- Navigate to Settings → Webhooks
- Enter your webhook URL (e.g.,
https://your-app.com/webhook) - Select the events you want to receive
- Enable Webhook Signing for security
- Save your configuration
Webhook Events
📩 message.inbound
Triggered when a new message is received from a user.
✅ message.delivered
Triggered when a message is successfully delivered to the recipient.
👁️ message.read
Triggered when a recipient reads your message.
📊 template.status
Triggered when a template status changes (approved, rejected, pending).
📱 campaign.completed
Triggered when a campaign finishes execution.
Webhook Payload Structure
{ "id": "evt_abc123", "event": "message.inbound", "timestamp": "2025-06-20T14:30:00Z", "data": { "from": "911234567890", "to": "911234567891", "text": "Hello from a customer!", "type": "text" } }
Webhook Security
To verify that webhook requests are coming from THEITBULLS, we sign each request with a signature.
Verifying Signatures
# Webhook signature header X-Webhook-Signature: sha256=2c7c3b8f9a1e5d6f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f # JavaScript example to verify const crypto = require('crypto'); function verifySignature(payload, signature, secret) { const expected = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); return signature === `sha256=${expected}`; }
Security best practice: Always verify webhook signatures to prevent malicious requests.
Handling Webhook Failures
If your webhook endpoint returns a non-200 status code, we'll retry with exponential backoff:
- Retry 1: 5 seconds
- Retry 2: 30 seconds
- Retry 3: 5 minutes
- Retry 4: 30 minutes
- Retry 5: 2 hours
- Max attempts: 10
Best Practices
- Respond quickly: Return 200 within 5 seconds
- Process asynchronously: Queue events for background processing
- Use idempotency: Handle duplicate events gracefully
- Log events: Keep a record for debugging
- Monitor webhooks: Track delivery success rates
Need help with webhooks? Our team is here to assist.
Get Support