Webhooks

Webhooks let Embarc push real-time events to your systems. Configure a webhook
once, subscribe it to the events you care about (e.g., “client created,” “loan
approved”), and Embarc will POST the payload to your endpoint every time the
event occurs.

What You Need

1. Webhook endpoint: HTTPS URL that can accept POST requests.
2. Content type: Choose JSON (recommended) or form-encoded when creating
   the webhook.
3. Authentication: Secure your endpoint (basic auth, API key, JWT) and
   validate incoming calls.
4. Retry strategy: Embarc sends each webhook once and retries a configurable X times on failure. If your endpoint returns a non-2xx status, the call is considered failed. Implement idempotency
   on your side in case of duplicate deliveries (network retries, manual replays).

Sample Event (Client Created)

When a new customer is created through POST /api/v1/clients, Embarc emits
the CLIENT + CREATE event. A webhook configured for that event receives a
JSON payload like this:

{
  "entityName": "CLIENT",
  "actionName": "CREATE",
  "createdBy": 12,
  "createdByName": "john.doe",
  "createdByFullName": "John Doe",
  "officeId": 3,
  "clientId": 9876,
  "timestamp": "2025-10-13T07:45:12Z",
  "request": {
    "firstname": "Alice",
    "lastname": "Martinez",
    "externalId": "CUST-2025-001",
    "submittedOnDate": "13 October 2025",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  },
  "response": {
    "resourceId": 9876,
    "officeId": 3
  }
}

• request mirrors the JSON the caller sent to Embarc.
• response contains the resource identifiers returned by the API.
• Timestamps are UTC; IDs are integer references you can look up via the
  standard APIs.

Configuration Steps

1. List template: GET /hooks/template to see available events
2. Create webhook: POST /api/v1/hooks with:
   JSON

   {
     "name": "client-events",
     "displayName": "Client creation hook",
     "isActive": true,
     "events": [
       { "entityName": "CLIENT", "actionName": "CREATE" }
     ],
     "config": [
       { "fieldName": "Payload URL", "fieldValue": "https://yourapp.example.com/webhooks/embrc" },
       { "fieldName": "Content Type", "fieldValue": "json" }
     ]
   }

3. Test delivery: Create a client in your sandbox environment and inspect
   the webhook call. Confirm status 200 and log the payload.

Operational Tips

• Idempotency: Use event fields (entity ID + timestamp) as a unique key to
  avoid processing duplicates.
• Timeouts: Aim to respond within a few seconds. Record the payload and
  process heavy work asynchronously.
• Security: Restrict the webhook endpoint by IP allowlists or require a
  shared secret in a header (e.g., X-Embarc-Signature that you validate).

Webhooks are the fastest way to keep downstream systems in sync with customer
and loan events. Configure them carefully, validate payloads, and Embarc will
push the updates you need in real time.