Overview
Webhooks deliver real-time HTTP callbacks when events happen in your Conduit account. Instead of polling the API, register an endpoint and Conduit pushes events to you.
Conduit guarantees at-least-once delivery — your endpoint may receive the same event more than once. Use the event id field to deduplicate.
Setting Up
1. Create an endpoint
curl -X POST https://api.conduit.financial/v2/webhooks/endpoints \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/conduit",
"eventTypes": ["application.approved", "application.rejected"]
}'
signingSecret. Save it securely — it is only shown once and cannot be retrieved later.
Pass eventTypes to subscribe to specific events, or omit it to receive all events.
2. Verify signatures
Every webhook request includes a signature in the X-Conduit-Signature header, computed as HMAC-SHA256 over the raw request body using your endpoint’s signing secret.
To verify:
- Read the raw request body (before any JSON parsing)
- Compute HMAC-SHA256 of the body using your signing secret
- Hex-encode the result and prepend
sha256=
- Compare with the
X-Conduit-Signature header value
# Example: computing the expected signature
echo -n '{"id":"evt_abc123",...}' | openssl dgst -sha256 -hmac "your-signing-secret"
# Output: sha256=a1b2c3d4...
Always verify signatures before processing webhook payloads. Reject requests where the signature does not match.
| Header | Description |
|---|
Content-Type | application/json |
X-Conduit-Signature | sha256={hmac-hex} — HMAC-SHA256 signature of the body |
X-Conduit-Delivery-Id | Unique ID for this delivery attempt |
X-Conduit-Event | The event type (e.g., application.approved) |
{
"id": "evt_...",
"type": "application.approved",
"created_at": "2026-01-15T09:30:00.000Z",
"data": {
"organizationId": "org_...",
"applicationId": "app_..."
}
}
data object varies by event type. Use the type field to determine how to process the payload.
Event Types
| Event | Description |
|---|
application.approved | A customer onboarding application was approved |
application.rejected | A customer onboarding application was rejected |
organization.approved | An organization onboarding application was approved |
organization.rejected | An organization onboarding application was rejected |
organization.activated | An organization was activated |
virtual_account_application.approved | A virtual account application was approved |
virtual_account_application.rejected | A virtual account application was rejected |
virtual_account.activated | A virtual account is active and ready to use |
virtual_account.rejected | A virtual account was rejected by the provider |
Use GET /v2/webhooks/event-types for the current list of available events. This table may not reflect newly added event types.
Delivery Lifecycle
Each webhook delivery goes through these statuses:
| Status | Description |
|---|
pending | Queued for delivery or scheduled for retry |
in_progress | Currently being delivered |
delivered | Your endpoint responded with a 2xx status |
failed | All retry attempts exhausted |
Retries
Failed deliveries are retried with increasing delays:
| Attempt | Delay |
|---|
| 1 | 30 seconds |
| 2 | 2 minutes |
| 3 | 15 minutes |
| 4 | 1 hour |
| 5+ | 4 hours |
curl -X POST https://api.conduit.financial/v2/webhooks/deliveries/wdl_.../retry \
-H "x-api-key: YOUR_API_KEY"
Managing Endpoints
| Operation | Endpoint |
|---|
| List endpoints | GET /v2/webhooks/endpoints |
| Get endpoint | GET /v2/webhooks/endpoints/:id |
| Update endpoint | PATCH /v2/webhooks/endpoints/:id |
| Delete endpoint | DELETE /v2/webhooks/endpoints/:id |
| List deliveries | GET /v2/webhooks/endpoints/:id/deliveries |
| Get delivery detail | GET /v2/webhooks/deliveries/:id |
Best Practices
- Respond quickly. Return a 2xx status within 5 seconds. Process the event asynchronously after acknowledging receipt.
- Deduplicate. Use the event
id to detect and skip duplicate deliveries.
- Verify signatures. Always validate
X-Conduit-Signature before processing the payload.
- Handle unknown events. Your endpoint may receive new event types as the API evolves. Return 2xx for events you don’t recognize — don’t reject them.
- Use HTTPS. Webhook endpoint URLs must use HTTPS.