Skip to content

Remittance Status Webhook Version 1.2#

SHIFT provides a webhook callback service to notify Send Agents when a remittance status changes to a final state:

  • Paidout
  • Canceled
  • Refunded

When a status update occurs, SHIFT sends an HTTP POST request to the partner’s registered webhook URL.

Webhook Endpoint#

Partners must expose an HTTPS endpoint to receive webhook notifications.

Endpoint Example

POST https://{partner-domain}/shift/webhook/v1/statusnotification

Requirements#

  • HTTPS is mandatory
  • Endpoint must accept JSON payloads
  • Webhook calls are secured using a secret token in the request header:
X-Shift-Token: <secret-token>

The tokens for Demo & Production environments will be provided by API Support team.

X-Shift-Token Handling#

The partner must:

  1. Read the X-Shift-Token header
  2. Validate it against the stored secret token
  3. Reject the request if the token is invalid
Scenario Response
Valid request 200 OK
Invalid token 401 Unauthorized or 403 Forbidden

Webhook Payload#

SHIFT sends a JSON payload in the request body.

{
    "eventId": "59854",
    "reference": "1234567895",
    "shiftReference": 23520254125,
    "currentStatus": "Paidout",
    "attempt": 1,
    "description": "",
    "updatedAt": "24/12/2025 11:35:54 AM",
    "statusDate": "24/12/2025 11:35:54 AM"
}

{
    "eventId": "59859",
    "reference": "1234567897",
    "shiftReference": 21235201478,
    "currentStatus": "Canceled",
    "attempt": 1,
    "description": "Due to compliance reason insufficient details",
    "updatedAt": "24/12/2025 11:36:54 AM",
    "statusDate": "24/12/2025 11:36:54 AM"
}

Fields Description#

Field Type / Format Description
eventId String Unique identifier for the webhook event
reference String Remittance tracking code (agent reference if provided)
shiftReference Integer (int64) SHIFT remittance number (11–14 digits)
currentStatus String Current transfer status
attempt Integer Webhook delivery attempt number
description String Only for Canceled status (reason)
updatedAt dd/MM/yyyy hh:mm:ss a Datetime when webhook was sent
statusDate dd/MM/yyyy hh:mm:ss a Datetime when status changed

Retry Policy#

SHIFT retries delivery if the webhook endpoint either:

  • Does not return HTTP 200 OK
  • Times out
  • Is unreachable

Retry Schedule#

Attempt Delay
1st failure After 1 minute
2nd failure After 5 minutes
3rd failure After 30 minutes
4th failure After 1 hour
5th failure After 2 hours

Additional Rules#

  • Each retry increments the attempt field
  • Maximum retry attempts: 5
  • After 5 failures → webhook marked as FAILED
  • Email notification is sent after final failure

Tip

Ensure your webhook endpoint responds within 5 seconds to avoid retries.

Email notification#

After final failure, SHIFT sends an email alert to the partner.

Email Sample

Important Notes#

  • SHIFT logs all webhook delivery attempts for audit and troubleshooting purposes.
  • Webhooks are delivered at least once
  • Delivery order is not guaranteed
  • Partner should handle duplicate events safely