Event-Triggered Callbacks

Last updated: Monday, March 20, 2023

Note

This feature is currently in progress with additional functionality coming soon. Reach out to your account rep to coordinate an implementation plan.

An Event-Triggered Callback can be returned after an Event is sent to Vibes. In order to determine whether or not your event succeeded or failed, you will need to understand the components of an Event Processed Callback and register to receive those callbacks.

Note: Events are primarily used for API-Triggered Messages. For more information on Events and their uses, please see our Event-Triggered Messages integration scenario.

Callback Flow

Example Callbacks

Skip to an example:

Routing Success
Routing Failures
Processing Failures
- No Incentive Codes
- Unexpected Error
Processing Callbacks
- SMS Queued

Skip to Elements & Attributes

Routing Success

If the Event that was received and the action is processing, you will see a success callback such as the one below.

{
  "event_id":"3a083a69-2064-430a-8ab6-72f163692ed2",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:02:36Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"routing",
        "status":"processing",
        "status_reason":"accepted_by_event_triggered_message",
        "resource_url": "/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
     }
  }
}

Potential Routing Failures

No Route Rules

This indicates that the system was not able to find an action in the system like an Event-Triggered Message to send the received Event to.

{
  "event_id":"fddbf770-f987-4928-91be-6b19c994562f",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:38:42Z",
  "event_processed":{
     "event_id":"5e9cabf7-228c-4f6e-944e-57b7728bc899",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"routing",
        "status":"failed",
        "status_reason":"event_routing_failed",
        "failure":{
           "reason":"no_route_rules_found_for_event"
        }
     }
  }
}

Person Doesn’t Belong To Associated Subscription List

This failure occurs if the person that is referenced in the Event doesn’t belong to the subscription list that is associated to the Event-Triggered Message.

{
  "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:20:02Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"routing",
        "status":"failed",
        "status_reason":"event_routing_failed",
        "failure":{
           "reason":"no_routes_accepted_event",
           "errors":[
              {
                 "error":"Event-Triggered Message subscription requirements are not met",
                 "resource_url": "/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
              }
           ]
        }
     }
  }
}

Person Not Found

This failure occurs when the person that is referenced in the Event is not found.

{
  "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:20:02Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"routing",
        "status":"failed",
        "status_reason":"event_routing_failed",
        "failure":{
           "reason":"no_routes_accepted_event",
           "errors":[
              {
                 "error":"Person is not found",
                 "resource_url": "/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
              }
           ]
        }
     }
  }
}

Carrier Not Supported

This failure occurs when the MDN referenced in the Event cannot be reached. This may be because the number is a landline, or it is on an unsupported carrier.

{
  "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:20:02Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"et127_no_incentive_codes",
     "event_data":{
        "mdn": "+18609740638",
        "something": "some value"
     },
     "action":{
        "type":"send_message",
        "status":"failed",
        "status_reason":"event_message_action_failed",
        "failure":{
           "reason":"PermanentLookupFailureError",
           "errors":[
              {
                 "error":"Carrier Lookup for +18609740638 failed with error null is not a mobile phone number or its carrier [null] is currently not supported",
                 "resource_url": "/companies/zY5VnE7r/mobiledb/event_triggered_messages/276"
              }
           ]
 
        }
     }
  }
}

Potential Processing Failures

No Incentive Codes

If the destination Event-Triggered Message is using an Incentive Pool and there are no incentive codes remaining to be used, you will receive this failure message.

{
  "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:20:02Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"send_message",
        "status":"failed",
        "status_reason":"event_message_action_failed",
        "failure":{
           "reason":"NoAvailableCodes",
           "errors":[
              {
                 "error":"The referenced incentive pool is out of codes.",
                 "resource_url": "/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
              }
           ]

        }
     }
  }
}

Unexpected Error

When some unexpected error has occurred during the Event-Triggered Message, you may receive this code.

{
  "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
  "callback_type":"event_processed",
  "event_date":"2022-08-15T20:20:02Z",
  "event_processed":{
     "event_id":"3b0e5871-d8b5-4393-b275-07ca0541c8de",
     "event_type":"day_of_delivery",
     "event_data":{
        "first_name":"Bob",
        "external_person_id":"abcd12345",
        "delivery_time":"5:00 PM",
        "order_url":"https://example.com/orders/12345"
     },
     "debug_data":{
        "field":"CUST_SYSTEM"
     },
     "action":{
        "type":"send_message",
        "status":"failed",
        "status_reason":"UnexpectedError",
        "failure":{
           "reason":"UnexpectedError",
           "errors":[
              {
                 "error":"Reason for unexpected error.",
                 "resource_url": "/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
              }
           ]

        }
     }
  }
}

Potential Processing Callbacks

SMS Message Queued To Be Sent To Carrier

You will receive this callback when an SMS message was successfully generated for an Event-Triggered Message and the message is queued to be sent to the carrier.

Note: The event_data and debug_data from the original Event will currently not be returned in the callback. This information is being worked on being provided in a future update.

{
   "event_id":"4a6dcfcf-16be-474d-b87f-ee64a08f6dab",
   "callback_type":"event_processed",
   "event_type":"event_processed",
   "event_date":"2022-08-15T20:20:02Z",
   "event_processed":{
      "event_id":"4810008e-800d-460c-94f2-a5d60a70f058",
      "event_type":"day_of_delivery",
      "event_data":{
         "first_name":"Bob",
         "external_person_id":"abcd12345",
         "delivery_time":"5:00 PM",
         "order_url":"https://example.com/orders/12345"
      },
      "debug_data":{
         "field":"CUST_SYSTEM"
      },
      "action":{
         "type":"send_message",
         "status":"processing",
         "status_reason":"queued",
         "message_type":"sms",
         "sms":{
            "source":{
               "resource_url":"/companies/:company_key/mobiledb/event_triggered_messages/:event_triggered_message_id"
            },
            "person":{
               "person_key":"w2e2127r-w413-841w-8t40-480b85dc6t3e",
               "resource_url":"/companies/:company_key/mobiledb/persons/w2e2127r-w413-841w-8t40-480b85dc6t3e"
            }
         }
      }
   }
}

Elements & Attributes of a Call

Field	Provided On	Description	Values
event_id	Success/Failure	Unique Event ID for the callback event.
event_date	Success/Failure	When the event occurred.	ISO-8601 YYYY-MM-DDTHH:MM:SSZ
callback_type	Success/Failure	The callback type that was registered for.	Will always be event_processed
event_type	Success/Failure	The `event_type` that was sent in the original Event.
event_data	Success/Failure	The `event_data` that was sent in the original Event.
debug_data	Success/Failure	The `debug_data` that was sent in the original Event.
action	Success/Failure	An object describing the details of the success or failure of the actions that were taken during the processing of the Event that was sent in to Public API.
action.type	Success/Failure		routing send_message
action.status	Success/Failure	Indication whether the action related to the Event is in a processing state, failed or succeeded.	success failed processing
action.status_reason	Success/Failure	Indicates the reason for the action status.
action.message_type	Processing/Failure	Indication of what type of message is being referenced.	sms
action.sms.source.resource_url	Processing/Failure (SMS)	The path to the resource that generated the message.
action.sms.person.person_key	Processing/Failure (SMS)	The person key identifier for the person that was associated to the message that was generated.
action.sms.person.resource_url	Processing/Failure (SMS)	The path to the person resource that was associated to the message that was generated.
failure	Failure	If a failure has occurred, this object will containing failure information for the action being described, including reason and error(s).

Additional Resources

For information on how to register your endpoint to receive callbacks, see Callback Configuration
Client Certificate Authentication for Callbacks from the Vibes Platform