Skip to main content

Best Practices

Follow these recommendations to build a reliable, secure, and maintainable webhook integration.

Respond Quickly​

SIPSIM enforces a 2-second timeout on webhook delivery. If your endpoint does not respond within this window, the delivery is considered failed.

Recommended approach: Return a 200 status immediately and process the event asynchronously using a background job queue.

@app.post("/webhook")
def handle_webhook(request):
    # Verify signature first
    if not verify_signature(request):
        return Response(status=401)

    # Queue for async processing — respond immediately
    background_queue.enqueue(process_event, request.json)

    return Response(status=200)

Verify Signatures​

Always validate the X-Webhook-Signature header to ensure requests genuinely originate from SIPSIM. See Signature Verification for implementation details.

Never skip signature verification, even in development — it helps catch configuration issues early.

Handle Duplicates​

Use the pbx_id field to deduplicate events. In rare cases (network retries, infrastructure failover), you may receive the same event more than once.

def process_event(event):
    cache_key = f"webhook:{event['event']}:{event['pbx_id']}"

    if cache.get(cache_key):
        return  # Already processed

    cache.set(cache_key, True, ttl=3600)
    # Process the event...

Use HTTPS​

Always use an HTTPS endpoint to protect webhook payloads in transit. HTTP endpoints are not accepted by SIPSIM.

Ensure your SSL certificate is valid and not expired — SIPSIM will refuse to deliver to endpoints with invalid certificates.

Log Everything​

Log incoming webhook payloads for debugging and audit purposes. This is invaluable when troubleshooting integration issues.

import logging

logger = logging.getLogger("webhooks")

@app.post("/webhook")
def handle_webhook(request):
    logger.info(
        "Webhook received",
        extra={
            "event": request.json.get("event"),
            "pbx_id": request.json.get("pbx_id"),
            "headers": dict(request.headers),
        }
    )
    # Process...

Monitor Failures​

If your endpoint is unreachable or returns errors, webhook delivery will not be retried. Set up monitoring to detect:

  • Endpoint downtime
  • High error rates on your webhook handler
  • Signature verification failures (may indicate a misconfigured secret)

Handle All Event Types Gracefully​

Your webhook handler should gracefully handle unknown event types. SIPSIM may introduce new events in the future, and your handler should not break when receiving them.

def process_event(event):
    handler = EVENT_HANDLERS.get(event["event"])

    if handler:
        handler(event)
    else:
        logger.warning(f"Unknown event type: {event['event']}")

Next Steps​