Introduction

Webhooks are used to push real-time notifications to a partner's pre-configured endpoint (callback URL). These notifications are triggered by business events within the MoneyGram platform, for example, when a transaction changes status.

The partner must setup a publicly accessible HTTPS endpoint to a defined specification provided by MoneyGram. The partner must then register/subscribe to a MoneyGram webhook subscription. MoneyGram systems will send real-time HTTPS POST requests to this endpoint with a JSON payload.

Partners can enroll in the 'Transaction Status Event' subscription. Enrollment in this subscription will provide real-time notification updates on the status and sub-status of a transaction, letting you know what’s happening with the transaction and any action required.

From these notifications partners can build an event based architecture, for example, you can use the webhook notification to update the customer that a transaction has been successfully received through an SMS, Email or push notification.

👍

Good to know:

Personal Identifiable Information (PII): 'Transaction Status Events' subscription and notifications will not contain any PII data.

---

General Webhook Sequence

Step 1: The User Transfers Funds for Cash Pick at MoneyGram location.

Step 2: A MoneyGram business event is generated when the funds are paid-out in store and the transaction status is changed to "received".

Step 3: MoneyGram triggers a webhook notification to notify the partner that the transaction's status has changed to "received". The webhook notification is pushed by an HTTP POST request to the partner's pre-configured endpoint (call back URL) as a JSON payload.

Step 4: The partner's call back URL process the webhook notification.

Step 5: The partner can choose to send an SMS, Email, or In-App notification to the user, letting them know their transaction has been successfully picked up at a MoneyGram location.

---

Creating a webhook subscription

1. Partners can work with their MoneyGram technical consultant to request a subscription.

2. MoneyGram will assign a subscriptionId for each requested webhook. Partners can subscribe to receive multiple subscriptions.
   

---

Creating a Webhook endpoint (Call Back URL)

1. The partner must setup a publicly accessible HTTPS endpoint and create a subscription with MoneyGram that uses this endpoint. MoneyGram's system will send HTTPS POST requests to this endpoint with events encoded in JSON.

2. Partner must provide a valid endpoint URL that meets these requirements:
   
   
   • A valid domain name (cannot include IPs)
   • Must use Port 443 to listen for HTTPS requests
   • Does not include query parameters

3. The partner is recommend to follow the below URL pattern:

👍

Good to know:

URL Pattern: MoneyGram recommends placing your business_name, moneygram and the webhook_status_events in the URL. This will help with both maintenance and troubleshooting.

---

Webhook Delivery

• The partner's server must respond with the following HTTP status within 10 seconds. MoneyGram recommends your processing logic should follow - once a notification is received do the security & schema validations and reply with a 200 response immediately.
  
  
  • HTTP 200 OK status for successfully receipt of the notification.
  • HTTP 400 Bad Request status for a notification that is not accepted. MoneyGram will not retry the request.
  • HTTP 500 Internal Server Error status for unsuccessful notification receipt. MoneyGram will retry the request.
    
    
• If MoneyGram does not receive an HTTP status response within 10 seconds, or receives a status code other that 200 the particular request will be considered for redelivery:
  
  
  • MoneyGram systems will try to redeliver 10 times within a span of 1 Hour (exponential back-off algorithm).
  • After 10 attempts have been made to redeliver the notification, if MoneyGram does not receive a 2XX status code response, the notification will be marked as "undelivered" and stored internally.
    
    
• MoneyGram will deliver the notifications sequentially but the partner can sort them chronologically by using the transactionSendDate .
• Partners will be given a unique id, and subscriptionId, associated with each notification for each subscription. Partners can subscribe to multiple notifications. Each subscribed notification will have a unique subscriptionId.

👍

Good to know:

Partner side downtime:

• In the event your server experiences down-time and MoneyGram is unable to to deliver a notification, you can request to "re-balance" all missing notifications. MoneyGram will work with you to provide all undelivered events.
• Where notification may be delivered out of sequence, the transactionSubStatus should be used to sort the events in date order.