Webhooks
Overview
Once the Emergency Workflow API is triggered, the partner's server and users technically fall into a "black box" in which RapidSOS provided a successful 2XX response indicating the flow has started, but there is no immediate method of knowing how the flow progresses.
Enter Webhooks. RapidSOS provides webhooks so that our partners can:
- Develop their own actions and processes based on the updates they receive from us.
- One example would be push notifications in an app to the user as they are waiting for help.
- Create their own reporting for what happens during the course of a flow.
Requirements
- For a Partner to receive webhooks, they must provide a server for us to send them to
- Ideally, it should have some sort of authentication.
- Only public IPs are permitted. Please discuss with your RapidSOS administrator if this will be a challenge.
Webhook Structure
| Field | Type | Description | Notes |
|---|---|---|---|
| alert_id | string | RapidSOS unique ID (parent session) | Also seen in response to initial API request to /rem endpoint |
| eventId | string | Partner's unique ID generated by its own server for the event (exists prior to the RSOS API request) | |
| userId | string | Partner's unique ID for the subscriber triggering the event | |
| verb | string | Verb to describe the action taking place | |
| message | string | Open text comments with description of actions taking place | |
| timestamp | number | the time the event occurred | Unix timestamp |
A signature header is also provided: x-rapidsos
Sample Webhook
When are webhooks sent?
At a minimum, webhooks are sent at all key decision points in a flow.
- Confirming receipt of the trigger and to indicate that the flow is starting
- Confirming that the user has been contacted
- Confirming the user’s decision to request help, decline, or no answer
- If help is needed, confirming that the call is being routed to 911
- Then confirming when the call with 911 ends
- If monitoring is included, confirming that the monitoring center has been notified
- If monitoring is included, confirming that the monitoring center has completed the alarm w/ the result (dispatch vs false alarm)
- When the flow has ended for any reason
List of Webhook Verbs
Note: A partner will only receive the webhooks that are relevant to their solution e.g. if you are not using a Monitoring solution, you will not receive those webhooks
| Verb | Description |
|---|---|
| flow.status.triggerReceived | Workflow is starting |
| flow.status.duplicateRequest | There is an existing request for the subscriber |
| flow.status.callingUser | Calling primary user |
| flow.status.primaryConfirm | Primary user confirmed a request for emergency services |
| flow.status.primaryCancel | Primary user canceled a request for emergency services |
| flow.status.primaryInvalidResponse | Primary user provided an invalid safeword or PIN |
| flow.status.primaryNoResponse | Primary user did not respond to the verification attempt |
| flow.status.primaryContactSupport | Primary user requested to contact Tech Partner support |
| flow.status.callingContact | Calling an emergency contact |
| flow.status.contactConfirm | Emergency contact confirmed a request for emergency services |
| flow.status.contactCancel | Emergency Contact canceled a request for emergency services |
| flow.status.primaryContactInvalidResponse | Emergency Contact provided an invalid safeword or PIN |
| flow.status.contactNoResponse | Emergency Contact did not respond to the verification attempt |
| flow.status.noAnswer | No call attempts were answered |
| flow.status.groupSms | Group SMS sent |
| flow.status.initiateSMS | SMS sent (2-way with 1 user only |
| flow.status.agentChatInitiated | 2-way SMS with a Monitoring Agent has started |
| flow.status.agentChatEnded | 2-way SMS with a Monitoring Agent has ended |
| flow.status.smsNoResponse | The user(s) did not respond to the verification attempt |
| flow.status.smsConfirm | User(s) confirmed a request for emergency services |
| flow.status.smsCancel | User(s) canceled a request for emergency services |
| flow.status.smsFail | The SMS did not reach the user(s) |
| flow.status.monitoring | The event is being escalated to a Monitoring Agent |
| flow.status.monitoringFail | The event could not be escalated to a Monitoring Agent |
| flow.status.monitoring_authorities_dispatched | The Monitoring Agent contacted emergency services |
| flow.status.monitoring_event_canceled | The Monitoring Agent did not request emergency dispatch due to lack of verification or user request |
| flow.status.flowEnd | The RapidSOS workflow has ended |
| flow.update.location | The new location was processed |
| flow.update.data | The data update was processed |
| flow.update.media | The new media file was processed |