Guides
Marketplace
Start typing to search…

Testing your Webhooks


Before relying on webhooks in production, you can validate your integration end-to-end using the sandbox testing endpoints. These let you preview what payloads look like, confirm your server can receive them, and inspect delivery history, all without waiting for a real data update.

Overview

The testing workflow has four steps:

  1. Preview the sample payload to see the exact JSON your server will receive.
  2. Review your webhook configuration to confirm the URL and auth settings are correct.
  3. Trigger a test delivery to send a real HTTP request to your endpoint and get immediate feedback.
  4. Check delivery history to review past test and production deliveries.

All sandbox endpoints use the same authentication as the rest of the API: pass your API key in the Authorization header.

Authorization: Basic <your_api_key>

Step 1: Preview the Sample Payload

Inspect the payload your webhook will receive before triggering a delivery.

curl -H "Authorization: Basic <your_api_key>" \
  https://api.daloopa.com/api/v2/webhooks/<webhook_id>/sample-payload

Response (200):

For a clientview_updated webhook:

{
  "test": true,
  "event_type": "clientview_updated",
  "company_id": 12345,
  "series": {
    "100001": { "periods": ["2025Q1", "2025Q2", "2025Q3"] },
    "100002": { "periods": ["2025Q1"] }
  }
}

For an incremental_update webhook:

{
  "test": true,
  "event_type": "incremental_update",
  "company_id": 12345,
  "series": {
    "100001": { "periods": ["2025Q1", "2025Q2"] },
    "100002": { "periods": ["2025Q3"] }
  }
}

For a series_updated webhook:

{
  "test": true,
  "event_type": "series_updated",
  "company_id": 12345,
  "series": [
    {
      "id": 99001,
      "type": "value_error",
      "period": "2025Q1",
      "run_date": "2025-01-15T10:30:00Z",
      "details": {
        "fundamental_id": 500001,
        "series_id": 100001,
        "field_changed": "fundamental_value",
        "new_value": "1250.75",
        "old_value": "1200.50"
      }
    },
    {
      "id": 99002,
      "type": "tagging_error",
      "period": "2025Q2",
      "run_date": "2025-01-15T10:31:00Z",
      "details": {
        "fundamental_id": 500002,
        "series_id": 100002,
        "field_changed": "fundamental_id",
        "new_value": 500010,
        "old_value": 500002
      }
    }
  ]
}

The sample payload matches the exact structure of real production payloads, with one addition: a top-level "test": true flag. See Handling the test flag for details.

Step 2: Review Your Configuration

Verify the URL and auth settings Daloopa will use when delivering to your endpoint.

curl -H "Authorization: Basic <your_api_key>" \
  https://api.daloopa.com/api/v2/webhooks/configurations

Response (200):

[
  {
    "id": 42,
    "event_type": "clientview_updated",
    "active": true,
    "is_test": false,
    "created_at": "2025-06-01T14:30:00Z",
    "configuration": {
      "url": "https://your-server.com/webhook",
      "event_type": "clientview_updated",
      "header_name": "Authorization",
      "prefix": "Bearer",
      "masked_auth_secret": "****7890"
    }
  }
]

Confirm that:

  • The url is correct and publicly reachable.
  • The header_name, prefix, and masked_auth_secret match the credentials your server expects.
  • active is true.

Step 3: Trigger a Test Delivery

Send a live HTTP POST to your webhook URL with the sample payload. Daloopa makes the request synchronously and returns the result immediately.

curl -X POST \
  -H "Authorization: Basic <your_api_key>" \
  https://api.daloopa.com/api/v2/webhooks/<webhook_id>/test

No request body is needed. The endpoint uses the sample payload for the webhook's event type.

Successful delivery (200):

{
  "success": true,
  "status_code": 200,
  "response_body": "OK",
  "duration_ms": 134
}

success is true when your server responds with any 2xx status code.

Failed delivery (200):

If your server returns a non-2xx status or is unreachable, the endpoint still returns 200 but with success: false:

{
  "success": false,
  "status_code": 502,
  "response_body": "Bad Gateway",
  "duration_ms": 2045
}

Timeout (200):

Test deliveries have a 10-second timeout. If your server does not respond in time:

{
  "success": false,
  "status_code": null,
  "response_body": "The webhook endpoint at https://your-server.com/webhook did not respond within 10 seconds",
  "duration_ms": 10003
}

Every test delivery is recorded in delivery history with is_test: true, so you can review results later.

Step 4: Check Delivery History

List past deliveries, optionally filtering to test-only results.

curl -H "Authorization: Basic <your_api_key>" \
  "https://api.daloopa.com/api/v2/webhooks/deliveries?is_test=true"

You can also filter by a specific webhook:

curl -H "Authorization: Basic <your_api_key>" \
  "https://api.daloopa.com/api/v2/webhooks/deliveries?webhook_id=42&is_test=true"

Response (200):

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 501,
      "timestamp": "2025-06-15T10:05:00Z",
      "event_type": "clientview_updated",
      "company_id": 12345,
      "response_status": 200,
      "response_body": "OK",
      "is_test": true,
      "duration_ms": 134
    },
    {
      "id": 500,
      "timestamp": "2025-06-15T09:58:00Z",
      "event_type": "clientview_updated",
      "company_id": 12345,
      "response_status": null,
      "response_body": "ConnectionError: ...",
      "is_test": true,
      "duration_ms": 5012
    }
  ]
}

Deliveries are returned in reverse chronological order. Pagination is supported via limit and offset query parameters (default and max page size: 500). Response bodies are truncated to 1000 characters in the listing.

Handling the Test Flag

Every test delivery payload includes "test": true at the top level. Production payloads do not include this field. Your webhook handler should check for this flag and skip any downstream processing when it is present.

Example handler logic:

import json

def handle_webhook(request):
    payload = json.loads(request.body)

    if payload.get("test"):
        return {"status": "ok", "message": "test received"}

    # Process the real event
    process_event(payload)
    return {"status": "ok"}

Creating a Test Webhook

When creating a webhook, you can set is_test to true to designate it as a test-only registration. Test webhooks are excluded from production delivery triggers, so they will only fire when you explicitly call the test endpoint. This is useful for validating your integration without receiving live data.

curl -X POST \
  -H "Authorization: Basic <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook-test",
    "event_type": "clientview_updated",
    "is_test": true,
    "header_name": "Authorization",
    "prefix": "Bearer",
    "auth_secret": "your-secret-token"
  }' \
  https://api.daloopa.com/api/v2/webhooks

Once you are confident your integration works, create a production webhook with is_test set to false (or update your existing webhook).

Troubleshooting

Webhook not found (404)

The webhook_id in the URL does not belong to your API key. Run GET /api/v2/webhooks/configurations to list your webhooks and confirm the correct ID.

Connection refused or DNS resolution failed

Your webhook URL is not publicly reachable. Verify that:

  • The URL uses https:// (recommended) or http://.
  • Your server is running and accessible from the internet.
  • Any firewall or security group rules allow inbound traffic on the correct port.

Authentication failures on your server

If your server returns 401 or 403 during a test delivery:

  • Check that the header_name and prefix on your webhook match what your server expects. For example, if your server expects Authorization: Bearer <token>, set header_name to Authorization and prefix to Bearer.
  • Verify the auth secret is correct. The configurations endpoint shows only the last 4 characters of your secret. If in doubt, update the webhook with a new auth_secret.

Timeout after 10 seconds

Test deliveries enforce a 10-second timeout. If your endpoint takes longer to respond:

  • Ensure your handler acknowledges the request quickly (return a 200 response immediately) and processes the payload asynchronously.
  • Check for network latency between Daloopa's servers and your endpoint.

Non-2xx response from your server

The test endpoint reports success: false for any response outside the 200 to 299 range. Review the response_body field in the test result or delivery history for error details from your server.

No deliveries in history

If your delivery history is empty after triggering a test:

  • Confirm you are querying with the correct webhook_id.
  • Remove the is_test filter to check if any deliveries exist at all.

Updated about 2 hours ago