Environments
How Harborline's IT team connects the dispatch system to RelayWorks for the rollout, from sandbox keys to production. Prepared by Omar Lewis, who supports the integration through Wave 1.
- Sandbox base URL
- https://sandbox.relayworks.example/v1
- Production base URL
- https://api.relayworks.example/v1
- Auth method
- OAuth 2.0 client credentials, 1 hour tokens
- Rate limit
- 300 requests per minute
- Integration support
- Omar Lewis, through Wave 1 go-live
- Target
- Production keys before Wave 1, Nov 16
Get connected
- Sandbox app createdClient ID issued Sep 22
- SSO and SCIM confirmedHarborline IT, due Sep 30
- Dispatch reference lookupRead only, in sandbox
- Webhooks and go-live checkBefore Nov 16
Step 1: Authenticate
Exchange the client ID and secret for an access token at POST /oauth/token. Cache the token and refresh it before it expires rather than requesting one per call.
Step 2: Attach a dispatch reference to a handoff
Call POST /handoffs with the account, region, owner and the dispatch job reference. RelayWorks stores the reference only. It never writes back to dispatch.
Core endpoints
| Method | Endpoint | Purpose | Scope |
|---|---|---|---|
| POST | /oauth/token | Exchange credentials for an access token | none |
| GET | /handoffs | List handoffs, filter by region, owner or status | handoffs:read |
| POST | /handoffs | Create a handoff with a dispatch job reference | handoffs:write |
| PATCH | /handoffs/{id} | Change owner or waiting reason | handoffs:write |
| POST | /webhooks | Register a webhook endpoint | webhooks:write |
| GET | /teams | Read teams synced from SCIM | teams:read |
Webhook flow for handoff updates
- handoff.created when the service desk hands work to a region.
- handoff.acknowledged when the receiving owner accepts it.
- handoff.owner_changed on region transfers and the after hours duty manager fallback.
Webhooks retry for 24 hours with backoff. Verify the signature header on every call.
Common error codes
| Code | Meaning | What to do |
|---|---|---|
| 401 | Token expired or invalid | Refresh the token, then retry once |
| 403 | Scope missing for this call | Ask Omar to add the scope to your client |
| 409 | Handoff already has an owner | Use PATCH to transfer ownership |
| 429 | Rate limit reached | Back off and retry after the stated delay |
Go-live checklist
- Sandbox client createddone
- Token refresh testeddone
- SCIM groups mapped to regional teamsopen
- Webhook signature verifiedopen
- Dispatch reference lookup tested on 20 real jobsopen
- Production keys issued after technical reviewopen
Next steps
- Harborline IT confirms the identity provider and SCIM groups by Sep 30.
- Omar schedules a 45 minute sandbox session for the week of Oct 5.
- Production keys are issued after signature, before Nov 16.