Skip to main content

Webhooks Overview

Webhooks allow you to receive real-time HTTP notifications when specific events occur in your Minteo account.

Events vs Hooks​

It's important to understand the distinction:

  • Event: A business occurrence that triggers a notification (e.g., an order reaches SUCCEEDED status)
  • Hook: An individual delivery attempt to notify your endpoint about an event

Example​

When an order reaches a final state:

  1. Minteo creates one Event with a unique event_id
  2. Minteo sends Hook #1 (first delivery attempt) to your endpoint
  3. If Hook #1 fails (non-200 response), Minteo sends Hook #2 (retry)
  4. This continues up to 14 hooks (delivery attempts) for the same event

When to use webhooks​

Use webhooks when you need to:

  • React immediately to state changes (final states for most entities, plus intermediate states for payins)
  • Avoid polling the API repeatedly
  • Build event-driven integrations
Payin webhooks

Payins trigger webhooks not only at final states (FULFILLED, ABORTED) but also when the payment gateway confirms the user completed the payment (status_code: GATEWAY_CONFIRM_PAYIN). This allows you to react immediately when the user pays, before the full tokenization process completes.

How it works​

┌─────────────────────────────────────────────────────────────┐
│  Entity reaches triggering state                            │
│  • Order: SUCCEEDED / FAILED                                │
│  • Payout: FULFILLED / ABORTED                              │
│  • Payin: IN_PROGRESS (status_code: GATEWAY_CONFIRM_PAYIN) /│
│           FULFILLED / ABORTED                               │
│  • Payout Item: SUCCEEDED / REJECTED                        │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  System creates unique Event                                │
│  event_id generated                                         │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
                    ┌──────────┐
                    │  Hooks   │
                    │configured│
                    │ in Board?│
                    └────┬─────┘
                         │
              ┌──────────┴──────────┐
              │                     │
             No                    Yes
              │                     │
              ▼                     ▼
      ┌──────────────┐    ┌─────────────────────┐
      │ End          │    │ Trigger Hook #1     │
      │ No           │    │ Immediate attempt   │
      │ notification │    └──────────┬──────────┘
      └──────────────┘               │
                                     ▼
                         ┌───────────────────────┐
                         │ POST to customer URL  │
                         │ Timeout: 10 seconds   │◀─────────────────┐
                         └──────────┬────────────┘                  │
                                    │                               │
                                    ▼                               │
                              ┌──────────┐                          │
                              │ Response │                          │
                              │   200?   │                          │
                              └────┬─────┘                          │
                                   │                                │
                        ┌──────────┴──────────┐                     │
                       Yes                    No                    │
                        │                     │                     │
                        ▼                     ▼                     │
              ┌──────────────────┐     ┌──────────┐                 │
              │ ✅ Success       │     │ Reached  │                 │
              │ Event marked as  │     │    14    │                 │
              │ SUCCEEDED        │     │ attempts?│                 │
              └──────────────────┘     └────┬─────┘                 │
                                            │                       │
                                 ┌──────────┴──────────┐            │
                                Yes                    No           │
                                 │                     │            │
                                 ▼                     ▼            │
                      ┌──────────────────┐   ┌─────────────────┐    │
                      │ ❌ Failed        │   │ ⏳ Wait with    │    │
                      │ Event marked     │   │ exponential     │    │
                      │ FAILED           │   │ backoff         │    │
                      └──────────────────┘   └────────┬────────┘    │
                                                      │             │
                                                      ▼             │
                                           ┌──────────────────┐     │
                                           │ Trigger next     │     │
                                           │ Hook (Attempt #N)│     │
                                           └────────┬─────────┘     │
                                                    │               │
                                                    │               │
                                                    └───────────────┘

Retry policy​

If your endpoint doesn't respond with HTTP 200:

  • Any non-200 status code triggers a retry
  • Timeouts (>10 seconds) trigger a retry
  • Minteo retries up to 14 times with exponential backoff
  • Total retry window: ~64 hours from first attempt

See Retry Schedule for the complete timing table.

Configuration​

Webhooks are configured in the Minteo Board (not via API):

Configure at: https://board.minteo.com/developers/hooks

info

Webhook configuration is currently only available through the Board UI. API-based configuration is not supported in v1.

Next steps​