Introduction
Catchpoint allows you to send BGP data collected over your BGP tests to your API endpoints. This feature enables you to retrieve raw BGP data returned in JSON format. When a BGP event is detected, the JSON data shall be posted to the endpoint. The data post can happen at most every minute per prefix.
Note: Unlike other Catchpoint webhook APIs, this webhook does not currently support the use of custom templates to modify output format.
Configuration
This can be enabled at the test level. If you need a different endpoint, it has to be configured at the Product level where all the BGP tests can be scheduled under a single Product.
For more details on how to setup test data webhook API endpoint in Catchpoint, you may refer to this article: Test Data Webhook Guide
Note: Unlike test data webhook, BGP post data is not sent by the nodes. Hence, you must whitelist the IP CIDR of our data center. 64.147.163.0/24
BGP Data Format
The BGP Data Webhook will post JSON data to your configured endpoint. The RAW data posted includes the following fields:
| Name | String Key | Byte Key | Data Type | Description |
|---|---|---|---|---|
| Peer | P | 1 | String (IP-Address) | Specifies the IP-address of the Peer. |
| Status | S | 2 | String | Specifies the status for the Peer. |
| Prefix | X | 3 | String (max=255) | Specifies the prefix for the given BGP Test for the given Peer. |
| Next Hop Address | H | 4 | String (IP-Address) | Specifies the next-hop address. |
| Origin | O | 5 | Character | Specifies the origin type, which has the following possible values: - e = EGP - ? = Incomplete - Default = IGP |
| ASN Path Values | A | 6 | String (for string-key) -or- Array of unsigned integers (for byte-key) |
Specifies the array of ASN Path values. For string-keys, this is a space delimited set of ASN Path values. |
| Community Values | C | 7 | String (for string-key) -or- Array of Strings (for byte-key) |
Specifies the array of Community values. For string-keys, this is a space delimited set of Community values. |
| Last Modified Timestamp (UTC) | M | 8 | String (YYYYMMDDHHMISS{MSC{MCR}}) | Specifies the last-modified timestamp (UTC) for the given Peer data. |
| Announcements | N | 9 | Byte | Indicates if any announcements were made for the given schedule window. Set to 1 if there are any. |
| Withdrawals | W | 10 | Byte | Indicates if any withdrawals were made for the given schedule window. Set to 1 if there are any. |
| Path changes[AI31][SB32] | E | 22 | Byte | Indicates the number of announcements where the AS path has changed vis-a-vis the previous event belonging to the very same network. New paths (i.e. from no path to path), path withdrawals (i.e. from path to no path), path changes, and path changing their prepending (e.g. from AS1 AS2 AS3 to AS1 AS2 AS3 AS3) will contribute to this metric |
| Aggregator | G | 18 | String (AS IP-Address) | A BGP attribute indicating that a router (not identifiable) did a route aggregation |
| Atomic aggregate | T | 19 | String (“AT”) if present | A BGP attribute indicating that a router identifiable by its IP address and AS number did a route aggregation, and some information has been lost due to the route aggregation process (potentially also the AS path) |
| Reachability Score | Y | 20 | See “BgpDataItemReachabilityScore” format | This object is present only for aBgpDataItemhaving the Prefix (X) equal to theBgpDataQuery Prefix (Q). |
| RPKI | R | 21 | See "BgpDataItemRpki" format | An object containing the RPKI status for the route being announced. The RPKI status of a route can be:·Unknown: in this case the field is omitted·Invalid: the origin AS is not authorized to advertise the network·Valid: the origin AS is authorized to advertise the network As per RPKI specification, the RPKI status of a route is valid if at least one RPKI record is found that says that is valid. This means that the presence of RPKI records that state the invalidity of a route are not sufficient to declare it invalid. |
BgpDataItemReachabilityScore
| Name | String Key | Byte Key | Data Type | Description |
|---|---|---|---|---|
| Numerator | N | 1 | Byte (0 or 1) | Specifies the contribution of the peer to the Reachability Score numerator. If not present, it is assumed to be zero. |
| Denominator | D | 2 | Byte (0 or 1) | Specifies the contribution of the peer to the Reachability Score denominator. If not present, it is assumed to be zero. |
BgpDataItemRpki
| Name | String Key | Byte Key | Data Type | Description |
|---|---|---|---|---|
| Matched | M | 1 | An array of BgpRpkiRecord. See "BgpRpkiRecord" format. |
Specifies the RPKI records that made the status valid. This field is required if the Status is "valid". |
| Unmatched Length | L | 2 | An array of BgpRpkiRecord. See "BgpRpkiRecord" format. |
Specifies the RPKI records that are not valid due to unmatched length. Either this field or "Unmatched AS" field must be present if the status is "invalid". This field may be present if the status is "valid". |
| Unmatched Origin ASN | A | 3 | An array of BgpRpkiRecord. See "BgpRpkiRecord" format. |
Specifies the RPKI records that are not valid due to unmatched origin ASN. Either this field or "Unmatched Length" field must be present if the status is "invalid". This field may be present if the status is "valid". |
BgpRpkiRecord
| Name | String Key | Byte Key | Data Type | Description |
|---|---|---|---|---|
| Asn | A | 1 | Four bytes integer | Specifies the ASN of the RPKI record |
| Prefix | P | 2 | String (max = 255) | Specifies the prefix of the RPKI record |
| Max-Length | M | 3 | Byte (max = 128) | Specifies the maximum length of the RPKI record. |
| Trust Anchor | T | 4 | String (max = 255) | Specifies the Trust Anchor of the RPKI record. |
JSON Sample
Sample RAW data in JSON format as seen on the endpoint:
{
"Asn": 6447,
"CityName": "Eugene",
"ClientId": 3xxx,
"ContinentId": 1,
"CountryName": "Costa Rica",
"DivisionId": 2xxx,
"NodeId": 4421xxx,
"NodeName": "RAI RouteViews route-views4",
"ReportWindow": "202212211700",
"Summary": {
"Bgps": [
{
"A": "141011 146989 61302 41051 58299 41327 210687",
"C": "58299:1100 6695:1000:1 61302:3:21000",
"H": "5.189.255.107",
"M": "20221221033618",
"O": "i",
"P": "5.189.255.107",
"R": {
"M": [
{
"A": 210687,
"M": 24,
"P": "45.156.61.0/24",
"T": "ripe"
}
]
},
"X": "45.156.61.0/24",
"Y": {
"D": 1,
"N": 1
}
},
{
"A": "14041 3356 41327 210687",
"C": "3356:2 3356:22 3356:100 3356:123 3356:505 3356:901 3356:2117 14041:101 65000:1257 65000:3292 65004:0",
"H": "192.43.217.143",
"M": "20221215141836",
"O": "i",
"P": "192.43.217.143",
"R": {
"M": [
{
"A": 210687,
"M": 24,
"P": "45.156.61.0/24",
"T": "ripe"
}
]
},
"X": "45.156.61.0/24",
"Y": {
"D": 1,
"N": 1
}
},
{
"A": "19754 1299 41327 210687",
"H": "198.98.84.183",
"M": "20221220082908",
"O": "i",
"P": "198.98.84.183",
"R": {
"M": [
{
"A": 210687,
"M": 24,
"P": "45.156.61.0/24",
"T": "ripe"
}
]
},
"X": "45.156.61.0/24",
"Y": {
"D": 1,
"N": 1
}
}
],
"Request": "45.156.61.0/24",
"Timestamp": "20221221170000000",
"Timing": {
"Total": 0
},
"V": 1
},
"TestDetail": {
"Labels": [
{
"UseCase": [
"Telecom"
]
},
{
"Customer": [
"Fibertelecom"
]
}
],
"MonitorTypeId": 34,
"Name": "BGP-45.156.61.0/24-AS41327",
"TypeId": 20
},
"TestId": 1305,
"TestRuntime": "20221221170000000",
"V": 6,
"Version": 4
}