Skip to content
C CountdownFlow Help Center Sign in

Managing and validating incoming webhooks

Securely receive event notifications by validating signatures and handling retry logic.

3 min read

Screenshots use fictional demo data. Your controls may differ by plan, role, or environment. Use the values generated in your own workspace.

Purpose of webhooks

API requests trigger actions within the app, while webhooks notify your HTTPS server that an event has occurred. Configure an endpoint to accept JSON POST requests and select only the specific events required by your integration.

Supported events include campaign.created, campaign.updated, campaign.published, campaign.paused, campaign.expired, campaign.viewed, campaign.clicked, conversion.created, recipient.started, recipient.first_opened and recipient.extended. Event availability does not indicate that an event confirms human interaction.

Testing endpoints

  1. 1Open API & webhooks and add the endpoint with at least one supported event.
  2. 2Use a public HTTPS address on port 443. Delivery safety checks do not support local/private addresses or redirecting endpoints.
  3. 3Store the endpoint signing secret securely on your receiver.
  4. 4Only use Send test when you are prepared; a signed sample can trigger live automation at the destination.
  5. 5Review delivery history, status and attempt logs, then test an actual event using a separate test campaign.
Webhook endpoint URL and supported event selection controls
Enter your public HTTPS receiver and select the events it needs. Save before testing, and remember that a signed test can trigger real automation. View full-size screenshot (opens in a new tab)

Verifying signatures

Check the X-CountdownFlow-Signature header. The format is t=TIMESTAMP,v1=SIGNATURE. The signature is an HMAC-SHA256 hash of the timestamp, a dot, and the raw HTTP body, generated using your webhook signing secret.

Reject stale timestamps based on your replay policy and compare signatures using a timing-safe function. Do not decode and re-encode the JSON before verification, as this alters the signed bytes. While the X-CountdownFlow-Event header identifies the event type, it is not a substitute for authentication.

// Receiver-side PHP example. Supply the secret from secure server storage. $raw = file_get_contents('php://input'); $header = $_SERVER['HTTP_X_COUNTDOWNFLOW_SIGNATURE'] ?? ''; $secret = getenv('COUNTDOWNFLOW_WEBHOOK_SECRET'); if (!$secret || !preg_match('/^t=(\d+),v1=([a-f0-9]{64})$/', $header, $m)) { http_response_code(401); exit; } if (abs(time() - (int) $m[1]) > 300) { http_response_code(401); exit; } $expected = hash_hmac('sha256', $m[1].'.'.$raw, $secret); if (!hash_equals($expected, $m[2])) { http_response_code(401); exit; } $event = json_decode($raw, true, 512, JSON_THROW_ON_ERROR); // Deduplicate the payload ID and enqueue trusted processing in your system. http_response_code(200);

Managing retry and deduplication

Deliveries may be retried. Because retries share the same logical payload ID, record this identifier and ensure your handler is idempotent before performing operations like granting access or creating orders.

Acknowledge events promptly to avoid retries, then process time-intensive tasks in your own background queue. Timeouts or non-successful responses may trigger a retry. Redirections are not followed. Diagnose failures through the delivery screen rather than exposing sensitive response bodies or credentials in support tickets.

Updating secrets

Disabling an endpoint also disables its tests. If you rotate your signing secret, update the receiver configuration securely and verify it. Do not confuse application-level webhooks with the platform’s separate internal billing-provider webhook setup.

Related articles