Card Batch Jobs: Webhook Flow

This workflow facilitates the secure transfer of batch card information between systems leveraging a webhook event model. After initial configuration on the eCard Systems (ECS) side, the partner (integrator) will build their system to work with the following data contracts.

Initial Configuration Details

A one time configuration will be required on the ECS side:

Name of integration
Partner GUID
Webhook URL (hosted by integrator)
Webhook Secret (securing above webhook)
Supply JWT Token (for use when integrator calls ECS's webhook below)

Workflow

ECS Originating Webhook: (block 2)

This is the data object that the integrator should expect to receive as the data contract.

{
  "job_guid": "",            // UUID - batch job identifier
  "partner_reference_id": "",  // STRING - Integrator's custom account/merchant/location combo ID
  "merchant_guid": "",       // UUID - ECS merchant identifier for this card batch
  "external_location_ids": [],  // Array of location ID's (smart track source)
  "record_count": 0,         // Integer - number of cards in batch
  "input_file_url": "",      // String - pre-signed download URL (SLA tied expiration)
  "result_upload_url": "",   // String - pre-signed upload URL for result file
  "expires_at": "",          // ISO timestamp - when URLs expire
  "callback_url": ""         // String - URL partner calls to confirm result upload
}

EXAMPLE:
{
    "job_guid": "cffde776-1d2a-4614-8023-a5148e411462",
    "partner_reference_id": "integrator-merchant1-location-002",
    "merchant_guid": "4933e450-d3c4-406f-9b9b-3afb812a5b7c",
    "external_location_ids": [
      "46691",
      "32049",
      "30730"
    ],
    "record_count": 200,
    "input_file_url": "https://xxxxx.s3.us-east-1.amazonaws.com/03338397-83da-470d-9cd7-241f6b5dbd62/cffde776-1d2a-4614-8023-a5148e411462/input.csv?X-Amz-Algorithm=AWS4-HMAC-SHA
  256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAQRDNACQH4SDURAEI%2F20260121%2Fus-east-1%2Fs3%2Faws4_request&2b80c26f5af912f3a671ed3e57bbc52ac0dd6aa7314d6d259cfdf5e65&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject",
    "result_upload_url": "https://xxxxx.s3.us-east-1.amazonaws.com/03338397-83da-470d-9cd7-241f6b5dbd62/cffde776-1d2a-4614-8023-a5148e411462/output.csv?X-Amz-Algorithm=AWS4-HMAC
  -SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAQRDNACQH4SDURAEI%2F20260121%2Fus-east-1%2Fs3%2Faws4_request&X-effbfbbbea42e089793e564e4c1af0fd80c3e84d1499e3c28a31b8cf969c2&X-Amz-SignedHeaders=host&x-amz-checksum-crc32=AAAAAA%3D%3D&x-amz-sdk-checksum-algorithm=CRC32&x-id=PutObject",
    "expires_at": "2026-01-22T22:43:59.295Z",
    "callback_url": "http://xxxxxx/api/reporting/v1/partner/batch-jobs/cffde776-1d2a-4614-8023-a5148e411462/result-uploaded"
  }

Integrator's Upload Confirmation Webhook (block 6)

When the integrator is ready to confirm the upload of the final batch CSV, the webhook URL to be used will be supplied in the callback_url value above but will be secured with a JWT Authentication token which will be supplied to the integrator during the initial setup process. Please note an OAuth2.0 flow will be coming soon for this.

Expected Webhook URL

This is what the callback URL will look like, but coding wise rely on the value provided in the above webhook package as the job ID is embedded in the URL.

EXAMPLE ONLY: https://XXXX/api/reporting/v1/partner/batch-jobs/cffde776-1d2a-4614-8023-a5148e411462/result-uploaded

Authentication Flow:

ECS generates a JWT for the partner during onboarding, signed with the platform's JWT_SECRET

Partner stores this token and includes it in the Authorization: Bearer token header when calling the webhook

Webhook Payload to be sent to ECS

{
    "success": true,
    "records_processed": 200,
    "records_failed": 0,
    "error_message": null
  }

Expected Response Payload from ECS

SUCCESS RESPONSE:
{
    "data": {
      "type": "batch-job-result",
      "id": "cffde776-1d2a-4614-8023-a5148e411462",
      "attributes": {
        "status": "RESULT_RECEIVED",
        "message": "Result upload confirmed",
        "received_at": "2026-01-21T22:50:00.000Z"
      }
    },
    "meta": {
      "timestamp": "2026-01-21T22:50:00.000Z",
      "requestId": "req-123456",
      "version": "1.0.0"
    },
    "jsonapi": {
      "version": "1.0"
    }
  }

ERROR RESPONSE:
{
    "errors": [
      {
        "status": "404",
        "title": "Job not found",
        "detail": "No batch job found with GUID cffde776-1d2a-4614-8023-a5148e411462"
      }
    ],
    "meta": {
      "timestamp": "2026-01-21T22:50:00.000Z",
      "requestId": "req-123456"
    },
    "jsonapi": {
      "version": "1.0"
    }
  }

Error State

If the process on the integrator's side experiences a problem with the file or other data eleements, they can return a "failure" message with a reason (error message) to inform eCards of the issue. This would be the expected Webhook POST body in that scenario:

{
    "success": false,
    "records_processed": 12,
    "records_failed": 150, //optional count of records that failed (per card number)
    "error_message": "error message up to 1,200 characters in length"
  }