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
- 1Open API & webhooks and add the endpoint with at least one supported event.
- 2Use a public HTTPS address on port 443. Delivery safety checks do not support local/private addresses or redirecting endpoints.
- 3Store the endpoint signing secret securely on your receiver.
- 4Only use Send test when you are prepared; a signed sample can trigger live automation at the destination.
- 5Review delivery history, status and attempt logs, then test an actual event using a separate test campaign.
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);
Your browser blocked clipboard access. Select the text and copy it manually.
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.