The Subscription Management section lets you configure webhook endpoints to receive real-time notifications about events in your Cobre account. When a payment completes, a balance changes, or a bulk file finishes processing, Cobre sends the details directly to your systems—no polling required.This keeps your internal tools in sync, enables automated workflows, and gives your team instant visibility into treasury operations.
Accessing Subscriptions#
Navigate to Developers > Webhooks in the sidebar. You'll see the Subscriptions table showing all your active webhook configurations.Viewing Your Subscriptions#
The Subscriptions table displays:| Column | Description |
|---|
| URL | The endpoint where Cobre sends notifications |
| Description | Your label for identifying this subscription |
| ID | System identifier (format: sub_XXXXXX) |
| Events | How many event types this subscription monitors |
| Creation date | When the subscription was created |
The table shows pagination info (e.g., "1-5 of 5") when you have multiple subscriptions.
Creating a Subscription#
Click + Create subscription in the top-right corner to open the creation form.Required Fields#
Webhook URL: The HTTPS endpoint that will receive notifications. This must be a publicly accessible URL that your server controls.Events: Select which event types you want to monitor. You can choose multiple events for a single subscription—for example, subscribing to all money movement status changes with one endpoint.Optional Fields#
Description: A friendly name to help you identify the subscription later. Examples: "ERP Integration," "Payment Alerts," "Accounting Sync."Secret Key: A passphrase (10-64 characters) used to sign notifications. When provided, Cobre includes a cryptographic signature with each webhook so you can verify authenticity. Store this key securely—you'll need it to validate incoming requests.After completing the form, click Create. Your subscription appears in the table immediately and begins receiving events.
Available Events#
Account Balance#
| Event Key | Trigger |
|---|
accounts.balance.credit | Funds received into your account |
accounts.balance.debit | Funds sent from your account |
Money Movements#
| Event Key | Trigger |
|---|
money_movements.status.initiated | Payment initiated |
money_movements.status.processing | Payment processing |
money_movements.status.pending_approval | Payment awaiting approval |
money_movements.status.completed | Payment completed |
money_movements.status.canceled | Payment canceled |
money_movements.status.returned | Payment returned |
money_movements.status.rejected | Payment rejected |
money_movements.status.failed | Payment failed |
Cross-Border Money Movements#
| Event Key | Trigger |
|---|
cross_border_money_movements.status.initiated | International transfer initiated |
cross_border_money_movements.status.processing | International transfer processing |
cross_border_money_movements.status.completed | International transfer completed |
cross_border_money_movements.status.rejected | International transfer rejected |
Bulk Money Movements#
| Event Key | Trigger |
|---|
bulk_money_movements.status.validating | Bulk file validating |
bulk_money_movements.status.processing | Bulk payments processing |
bulk_money_movements.status.pending_approval | Bulk file awaiting approval |
bulk_money_movements.status.completed | Bulk processing completed |
bulk_money_movements.status.canceled | Bulk file canceled |
bulk_money_movements.status.failed | Bulk processing failed |
Cobre Keys#
| Event Key | Trigger |
|---|
cobre_keys.status.processing | Key registration in progress |
cobre_keys.status.registered | Key registered |
cobre_keys.status.unregistered | Key unregistered |
cobre_keys.status.disabled | Key disabled |
cobre_keys.status.failed | Key registration failed |
Other Events#
| Event Key | Trigger |
|---|
reports.created | Report generated |
evidence-request.ask | Evidence request created |
Deleting a Subscription#
Hover over any subscription row to reveal the delete action. Deleting a subscription stops all notifications to that endpoint immediately.If you need to change events or the URL, delete the existing subscription and create a new one with the updated configuration.
Webhook Security#
Signature Verification#
When you include a secret key during creation, every notification includes two headers:| Header | Content |
|---|
event-timestamp | UTC timestamp of event creation |
event-signature | 64-character SHA256 HMAC hash |
To verify a notification:1.
Concatenate the timestamp and raw body: {event-timestamp}.{body}
2.
Calculate HMAC-SHA256 using your secret key (UTF-8 encoding)
3.
Compare your result to the event-signature header
Delivery Retries#
Cobre retries failed deliveries automatically:| Attempt | Delay |
|---|
| 1st retry | 200ms |
| 2nd retry | 400ms |
| 3rd retry | 1000ms |
Retries only apply to connection errors. If your endpoint returns a 4xx status, Cobre does not retry—so always return 2xx for successful receipt.
Best Practices#
Use HTTPS endpoints. HTTP is not supported. Ensure your webhook URL uses encrypted transmission.Return 2xx quickly. Acknowledge receipt immediately, then process the event asynchronously. Long processing times risk timeouts.Implement idempotency. Use the event id to handle potential duplicate deliveries gracefully.Secure your secret key. Treat it like a password. If compromised, delete the subscription and create a new one.Subscribe selectively. Start with only the events you need. You can always create additional subscriptions later.
Troubleshooting#
Not receiving notifications? Verify your endpoint is publicly accessible, uses HTTPS, and returns a 2xx response.Signature mismatch? Check that you're using the raw body (no reformatting), correct concatenation order, and UTF-8 encoding.Missing events? Confirm the subscription includes the event types you expect. Check the Events column in the table. Modified at 2025-12-24 15:47:59
