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.