1. Introduction
Webhooks allow services like order related events and notifications to send real-time data to clients over the web. This document provides a detailed explanation of the structure and components of webhook payloads, including examples for various event types.
2. Event Types
A list of all possible event types that can trigger a webhook:
- NewCsrRequested
- PreOrderStatusChanged
- PreOrderPortOutSubmitted
- PreOrderSupplemented
- PreOrderSupplementAnswered
- VpopPortOutCsrRequested
- Authorized
- SvCreate
- SvDisconnect
- SvActivate
- SvModifyActive
- SvModify
- SvConflict
- SvActivated
- SvCancel
- SvCanceled
- NotesAdded
- TaskAssigned
- NumberGatewayOrderStatusUpdated
3. Payload Structure
The payload is the data sent to the configured URL when an event is triggered. The common components of a webhook payload include:
3.1 Event Type
Indicates the type of event that triggered the webhook.
- Field Name: Type
- Type: String
- Example: "Type": "PreOrder"
3.2 Timestamp
The date and time when the event occurred.
- Field Name: Timestamp
- Type: String
- Example: "Timestamp": "2024-06-22T14:44:53.6892844+00:00"
3.3 Tenant Id
The unique identifier of the tenant related to the event.
- Field Name: Tenant
- Type: String
- Example: "Tenant": "A221"
3.4 Reply
The type of resource related to the event reply from NPAC.
- Field Name: Reply
- Type: bool
- Example: "Reply": true
3.5 Success
The type of resource related to the event which is success.
- Field Name: Success
- Type: String
- Example: "Success": true
3.6 Error Message
The type of resource related to the event which is error messages if any.
- Field Name: ErrorMessage
- Type: String
- Example: "ErrorMessage": null
Payload
Contains detailed information about the event and the intended message or payload.
- Field Name: payload
- Type: Object
- Example:
{
"Type": "Order",
"Tenant": "A221",
"Reply": true,
"Success": true,
"ErrorMessage": null,
"Action": "SvCancel",
"Timestamp": "2024-03-30T01:27:14.9319589Z",
"Payload": {
"OrderId": "A221-638473579620853036",
"ProjectId": null,
"NewSpId": null,
"OldSpId": null,
"StartTn": null,
"StopTn": null,
"Status": null,
"NewDueDate": null,
"OldDueDate": null,
"ConflictCode": null
}
}
4. Security Considerations
To ensure the security of webhook payloads:
4.1 Verification Token
Include a authorization token in the headers of the payload to ensure the request is legitimate.
- Field Name: Bearer
- Type: String
- Example: Bearer 7ff00389d6a745ceb31ecb4e213cc0aa
4.2 IP Whitelisting
Configure the server to accept requests only from known IP addresses.
4.3 TLS/SSL
Ensure that the webhook endpoint uses HTTPS to encrypt data in transit.
5. Examples
1. NewCsrRequested
{
"Type": "Csr",
"Tenant": null,
"Reply": false,
"Success": true,
"ErrorMessage": null,
"Action": "NewCsrRequested",
"Timestamp": "2024-08-01T09:06:42.164848Z",
"Payload": {
"OrderId": "A221-638580999969085847",
"GainingProvider": "A221",
"LosingProvider": "A222",
"DueDate": "2024-08-01T00:00:00\u002B00:00",
"CustomerDetails": {
"AccountType": 0,
"AccountNumber": "",
"AccountName": "N/A",
"AccountPin": "",
"AuthorizedName": "8472742349",
"BillingPhoneNumber": "8472742349",
"ServiceAddress": {
"DirectionPrefix": "",
"StreetName": "",
"StreetNameSuffix": "",
"DirectionSuffix": "",
"AddressLine2": "",
"Number": "",
"City": "",
"ZipCode": "",
"State": "",
"LocationDesignator": null,
"LocationValue": null
}
}
}
}
2. PreOrderStatusChanged
{
"Type": "PreOrder",
"Tenant": null,
"Reply": false,
"Success": true,
"ErrorMessage": null,
"Action": "PreOrderStatusChanged",
"Timestamp": "2024-08-01T10:00:06.3952034Z",
"Payload": {
"OrderId": "A221-638581031746925388",
"OrderType": "Port-In",
"IsPreOrder": true,
"IsFreeOrder": false,
"NewStatus": "CSR Modified",
"OldStatus": "CSR Pending",
"CustomerDetails": {
"AccountType": 0,
"AccountNumber": "",
"AccountName": "8472742374",
"AccountPin": "",
"AuthorizedName": "8472742374",
"BillingPhoneNumber": "8472742374",
"ServiceAddress": {
"DirectionPrefix": "",
"StreetName": "",
"StreetNameSuffix": "",
"DirectionSuffix": "",
"AddressLine2": "chicago",
"Number": "",
"City": "",
"ZipCode": "",
"State": "",
"LocationDesignator": null,
"LocationValue": null
}
},
"LastNoteText": "Account information updated",
"LastNoteUser": "testpcadmin@test.com",
"Numbers": [
"8472742374"
],
"Timestamp": "2024-08-01T10:00:06.3952075Z",
"MailAttachments": null,
"messageType": null
}
}
3. PreOrderPortOutSubmitted
{
"Type": "PreOrder",
"Tenant": "A222",
"Reply": false,
"Success": null,
"ErrorMessage": null,
"Action": "PreOrderPortOutSubmitted",
"Timestamp": "2024-08-01T09:54:44.7244032Z",
"Payload": {
"OrderId": "A222-638581028845593835",
"GainingProvider": "505B",
"PortToOriginal": false,
"LosingProvider": "A222",
"DesiredDueDate": "2024-08-01T00:00:00Z",
"Numbers": [
"8472742360"
],
"CustomerDetails": {
"AccountType": 0,
"AccountNumber": "",
"AccountName": "8472742360",
"AccountPin": "",
"AuthorizedName": "8472742360",
"BillingPhoneNumber": "8472742360",
"ServiceAddress": {
"DirectionPrefix": "",
"StreetName": "",
"StreetNameSuffix": "",
"DirectionSuffix": "",
"AddressLine2": "chicago",
"Number": "",
"City": "",
"ZipCode": "",
"State": "",
"LocationDesignator": null,
"LocationValue": null
}
},
"messageType": null
}
}
4. PreOrderSupplemented
{
"Type": "PreOrder",
"Tenant": "A222",
"Reply": false,
"Success": null,
"ErrorMessage": null,
"Action": "PreOrderSupplemented",
"Timestamp": "2024-08-01T07:24:33.7618899Z",
"Payload": {
"OrderId": "A222-638580938420841010",
"SupplementType": "Other",
"GainingProvider": "A221",
"LosingProvider": "A222",
"Numbers": [
"8472740086"
],
"Canceled": false,
"DueDate": "2024-08-01T00:00:00Z",
"CustomerDetails": {
"AccountType": 0,
"AccountNumber": "",
"AccountName": "test",
"AccountPin": "",
"AuthorizedName": "testt",
"BillingPhoneNumber": "8472740086",
"ServiceAddress": {
"DirectionPrefix": "",
"StreetName": "",
"StreetNameSuffix": "",
"DirectionSuffix": "",
"AddressLine2": "",
"Number": "",
"City": "",
"ZipCode": "",
"State": "",
"LocationDesignator": null,
"LocationValue": null
}
},
"messageType": null
}
}
5. PreOrderSupplementAnswered
{
"Type": "PreOrder",
"Tenant": "A221",
"Reply": false,
"Success": null,
"ErrorMessage": null,
"Action": "PreOrderSupplementAnswered",
"Timestamp": "2024-08-01T08:52:50.7989454Z",
"Payload": {
"OrderId": "A221-638580991427779258",
"Approved": true,
"RejectionCode": null,
"RejectionReason": null,
"FocDate": "2024-08-01T00:00:00Z",
"messageType": null
}
}
6. VpopPortOutCsrRequested
{
"Type": "Csr",
"Tenant": "A221",
"Reply": false,
"Success": true,
"ErrorMessage": null,
"Action": "VpopPortOutCsrRequested",
"Timestamp": "2024-08-01T05:30:54.8062153Z",
"Payload": {
"OrderId": "S222-638580870540794340",
"GainingProvider": "A221",
"LosingProvider": "S222",
"DueDate": "2024-08-01T00:00:00\u002B00:00",
"CustomerDetails": {
"AccountType": 0,
"AccountNumber": "",
"AccountName": "N/A",
"AccountPin": "",
"AuthorizedName": "5274509990",
"BillingPhoneNumber": "5274509990",
"ServiceAddress": {
"DirectionPrefix": "",
"StreetName": "",
"StreetNameSuffix": "",
"DirectionSuffix": "",
"AddressLine2": "",
"Number": "",
"City": "",
"ZipCode": "",
"State": "",
"LocationDesignator": null,
"LocationValue": null
}
},
"MailAttachments": [],
"AccountType": "Residential",
"Status": "VpopPortoutCsr",
"messageType": null
}
}
7. Authorized
{
"Type": "Order",
"Tenant": "A222",
"Reply": true,
"Success": true,
"ErrorMessage": null,
"Action": "Authorized",
"Timestamp": "2024-07-23T09:24:13.1907646Z",
"Payload": {
"OrderId": "A222-638573234502506058",
"ProjectId": null,
"NewSpId": "A222",
"OldSpId": "S222",
"StartTn": "8472740312",
"StopTn": "8472740312",
"Status": null,
"NewDueDate": null,
"OldDueDate": null,
"ConflictCode": null,
"messageType": null
}
}
8. SvCreate
{
"Type": "Order",
"Tenant": "A221",
"Reply": true,
"Success": true,
"ErrorMessage": null,
"Action": "SvCreate",
"Timestamp": "2024-08-01T09:50:34.0074013Z",
"Payload": {
"OrderId": "A221-638581026323554798",
"ProjectId": null,
"NewSpId": null,
"OldSpId": null,
"StartTn": null,
"StopTn": null,
"Status": null,
"NewDueDate": null,
"OldDueDate": null,
"ConflictCode": null,
"messageType": null
}
}
9. SvDisconnect
{
"Type": "Order",
"Tenant": "A221",
"Reply": true,
"Success": true,
"ErrorMessage": null,
"Action": "SvDisconnect",
"Timestamp": "2024-07-23T09:40:51.9206221Z",
"Payload": {
"OrderId": "A221-638573244504643186",
"ProjectId": null,
"NewSpId": null,
"OldSpId": null,
"StartTn": null,
"StopTn": null,
"Status": null,
"NewDueDate": null,
"OldDueDate": null,
"ConflictCode": null,
"messageType": null
}
}
10. SvActivate
{
"Type": "Order",
"Tenant": "A221",
"Reply": true,
"Success": true,
"ErrorMessage": null,
"Action": "SvActivate",
"Timestamp": "2024-08-01T08:53:08.6867718Z",
"Payload": {
"OrderId": "A221-638580991427779258",
"ProjectId": null,
"NewSpId": null,
"OldSpId": null,
"StartTn": null,
"StopTn": null,
"Status": null,
"NewDueDate": null,
"OldDueDate": null,
"ConflictCode": null,
"messageType": null
}
}
11. SvModifyActive
{
"Type": "Order",
"Tenant": "A221",
"Reply": true,
"Success": true,
"ErrorMessage": null,
"Action": "SvModifyActive",
"Timestamp": "2024-07-23T10:12:39.0940928Z",
"Payload": {
"OrderId": "A221-638573263573390152",
"ProjectId": null,
"NewSpId": null,
"OldSpId": null,
"StartTn": null,
"StopTn": null,
"Status": null,
"NewDueDate": null,
"OldDueDate": null,
"ConflictCode": null,
"messageType": null
}
}
12. SvModify
{
"Type": "Order",
"Tenant": "A221",
"Reply": true,
"Success": true,
"ErrorMessage": null,
"Action": "SvModify",
"Timestamp": "2024-08-01T07:25:36.0592764Z",
"Payload": {
"OrderId": "A221-638580938418646887",
"ProjectId": null,
"NewSpId": null,
"OldSpId": null,
"StartTn": null,
"StopTn": null,
"Status": null,
"NewDueDate": null,
"OldDueDate": null,
"ConflictCode": null,
"messageType": null
}
}
13. SvConflict
{
"Type": "Order",
"Tenant": "A222",
"Reply": true,
"Success": true,
"ErrorMessage": null,
"Action": "SvConflict",
"Timestamp": "2024-08-01T07:15:19.0025468Z",
"Payload": {
"OrderId": "A222-638580932716180204",
"ProjectId": null,
"NewSpId": null,
"OldSpId": null,
"StartTn": null,
"StopTn": null,
"Status": null,
"NewDueDate": null,
"OldDueDate": null,
"ConflictCode": null,
"messageType": null
}
}
14. SvActivated
{
"Type": "Order",
"Tenant": "A222",
"Reply": true,
"Success": true,
"ErrorMessage": null,
"Action": "SvActivated",
"Timestamp": "2024-08-01T07:07:47.0985597Z",
"Payload": {
"OrderId": "test5",
"ProjectId": null,
"NewSpId": "A222",
"OldSpId": "A222",
"StartTn": "8472740092",
"StopTn": "8472740092",
"Status": null,
"NewDueDate": null,
"OldDueDate": null,
"ConflictCode": null,
"messageType": null
}
}
15. SvCancel
{
"Type": "Order",
"Tenant": "A221",
"Reply": true,
"Success": true,
"ErrorMessage": null,
"Action": "SvCancel",
"Timestamp": "2024-07-31T21:54:35.5488761Z",
"Payload": {
"OrderId": "A221-638580594749026124",
"ProjectId": null,
"NewSpId": null,
"OldSpId": null,
"StartTn": null,
"StopTn": null,
"Status": null,
"NewDueDate": null,
"OldDueDate": null,
"ConflictCode": null,
"messageType": null
}
}
16. SvCanceled
{
"Type": "Order",
"Tenant": "A222",
"Reply": true,
"Success": true,
"ErrorMessage": null,
"Action": "SvCanceled",
"Timestamp": "2024-07-23T04:37:16.9307397Z",
"Payload": {
"OrderId": "A222-638573062145783553",
"ProjectId": null,
"NewSpId": "A222",
"OldSpId": "A221",
"StartTn": "8472741000",
"StopTn": "8472741000",
"Status": null,
"NewDueDate": null,
"OldDueDate": null,
"ConflictCode": null,
"messageType": null
}
}
17. NotesAdded
{
"Type": "Order",
"Tenant": null,
"Reply": false,
"Success": true,
"ErrorMessage": null,
"Action": "NotesAdded",
"Timestamp": "2024-05-09T10:43:29.338808Z",
"Payload": {
"OrderId": "Y228-638508471721894827",
"GainingProvider": "Y228",
"LosingProvider": "Y128",
"DueDate": "2024-05-22T00:00:00",
"Status": "CSRReceived",
"Note": "Generic",
"NoteBy": "carlter@numbhub.com"
}
}
18. TaskAssigned
{
"Type" = "NumberGateway",
"Action" = "Submitted",
"Tenant" = S222,
"Timestamp" = "2024-07-22T07:24:33.7618899Z",
"Success" = true,
"ErrorMessage" = null,
"Reply" = false,
"Payload" = {
"OrderId" = "S222-638473579620853036",
"Title" = "NumbHub",
"Description" = "ch status for 7/26 DDD",
"WorkDate" = "2024-07-22T00:00:00",
"AssignedTo" = "john@numbhud.com"
"AssignedFrom" = "carlter@numbhub.com"
}
}
6. Error Handling
Information on how to handle errors, such as retry mechanisms and logging:
- Retries: 3.
- Logging: Log webhook events and errors for debugging purposes.
- Alerts: For failed webhook deliveries.
-Ability to retry failed notifications in UI available.
Comments
0 comments
Please sign in to leave a comment.