Guides

Performance Results Webhook

You can send an alert for every API call you make, or just those that have failed or generated a warning

Suggest Edits

If you'd like to use a custom integration, you can use our Performance Webhooks to receive alerts on API call results.

To set it up, you just need to provide us with a URL that is publicly accessible. This could be something as simple as a AWS Lambda or a Google Cloud function.

We use a HTTP POST to send you the following data:

{   call_id: str
    call_url: str
    call_meta:
        name: str
        description: str
        tags: list[str]
        domain: str
    project_meta: 
	  	  name: str
        organization: str
        tags: list[str]
    result_id: str
    result_url: str
    result: str
    result_class: str
    location_id: str
    response_size: int | null
    response_time: int | null
    context: dict[str, Any]
    http_code: int
    http_reason: str
    workflow_id: str | null = null
    workflow_name: str | null = null
    workflow_result_id: str | null = null
    workflow_url: str | null = null
    workflow_result_url: str | null = null
    start_time: str | null = null
    target_data: [NOTE: may be null] 
        ip_addr: str
        cloud: str | null = null
        city: str | null = null
        region: str | null = null
        country: str | null = null
        continent: str | null = null
        latitude: str | null = null
        longitude: str | null = null
        network: str | null = null
        cdn: str | null = null
        asn: str | null = null
    timing_data: [NOTE: may be null] 
        dns: int | null
        connect: int | null
        tls_handshake: int | null
        upload: int | null
        processing: int | null
        download: int | null
        total: int | null
    location_data:  [NOTE: may be null] 
        ip_addr: str
        cloud: str | null = null
        city: str | null = null
        region: str | null = null
        country: str | null = null
        continent: str | null = null
        latitude: str | null = null
        longitude: str | null = null
    dns_records:  [NOTE: may be null] 
        a: list[str] | null
        ns: list[str] | null
        cname: list[str] | null

Note that the result_class will be one of PASS, SLOW, WARNING, or FAIL.
The result is more granular - those can be:

  • For WARNING class: CONNECTION_WARNING, HTTP_REDIRECT_ERROR, HTTP_CLIENT_ERROR, CONTENT_WARNING, SLA_WARNING.
  • For FAIL class: HTTP_SERVER_ERROR, CONNECTION_ERROR, HEADER_ERROR, CONTENT_ERROR, SLA_ERROR.
  • For PASS class: COMPLETE.
  • For SLOW class: SLOW_COMPLETE.

Here are the definitions for each field in the webhook:

  • call_id: The APIContext identifier for the Call ID - this is a static ID that will be the same every time the call is made. Used for correlating results with the same call parameters.
  • call_url: URL link to the APIContext API Call configuration/summary page associated with this API Call.
  • call_meta: These fields are set during call configuration.
    • name: The name of the APIContext API call - this is set during call configuration.
    • description: A text description providing more information about a specific API call.
    • tags: A list of tags associated with the APIConext API Call.
    • domain: The domain name of the APIContext API call.
  • project_meta: These fields are set during organization and project configuration.
    • name: The name of the APIContext API call.
    • organization: The APIContext organization name where the project can be found.
    • tags: A list of tags associated with the Project.
  • result_id: A unique identifier assigned to a specific result. This will be unique for every call.
  • result_url: This is the URL link that takes you to the APIContext API Results page for this single request.
  • result: The specific status explaining the reason for result_class in more detail, e.g. ‘Complete’, ‘Skipped’, ‘SLA Warning’, etc.
    • For FAIL class: HTTP_SERVER_ERROR, CONNECTION_ERROR, HEADER_ERROR, CONTENT_ERROR, SLA_ERROR.
    • For PASS class: COMPLETE.
    • For SLOW class: SLOW_COMPLETE
    • For WARNING class: CONNECTION_WARNING, HTTP_REDIRECT_ERROR, HTTP_CLIENT_ERROR, CONTENT_WARNING, SLA_WARNING.
  • result_class: The result of the test.
    • FAIL: Indicates the call has returned a response code with a FAIL condition. Usually, this indicates a 4xx or 5xx response, but can be set during alert configuration.
    • PASS: Indicates the call has returned a response code with a PASS condition. Usually, this indicates a 2xx response, but can be set during alert configuration.
    • SLOW: Indicates the call has returned a response code with a slow response. The expected response time can be set during alert configuration.
    • WARNING: Indicates the call has returned a response code with a WARNING condition, which can be set during alert configuration.
  • location_id: Unique identifier of the APIContext agent location - e.g. apimetrics_azurenorwayeast.
  • response_size: The size of the response data returned from a request, measured in bytes.
  • response_time: The number of milliseconds (ms) the response took to fully download.
  • context: APIContext internal reference fields used for analysis and de-bugging only.
  • http_code: The http response code.
    • 1xx informational response – the request was received, continuing process
    • 2xx successful – the request was successfully received, understood, and accepted
    • 3xx redirection – further action needs to be taken in order to complete the request
    • 4xx client error – the request contains bad syntax or cannot be fulfilled
    • 5xx server error – the server failed to fulfil an apparently valid request
  • http_reason: A brief description or phrase associated with an HTTP status code, explaining the reason for the response (e.g., "OK" for a 200 code).
  • workflow_id: The APIContext workflow ID associated with the request. Please note this will be empty if the request is not part of a workflow.
  • workflow_name: The name of the workflow associated with the request. Please note this will be empty if the request is not part of a workflow.
  • workflow_result_id: A unique identifier for the result of a specific APIContext workflow execution. Please note this will be empty if the request is not part of a workflow.
  • workflow_url: A URL pointing to the workflow configuration/summary page. Please note this will be empty if the request is not part of a workflow.
  • workflow_result_url: A URL linking to the APIContext workflow result page for the workflow associated with the request. Please note this will be empty if the request is not part of a workflow.
  • start_time: The timestamp when the call was instantiated.
  • target_data: [NOTE: may be null]
    • ip_addr: The IP address of the target endpoint.
    • cloud: The cloud service provider where the target endpoint is located.
    • city: The city where the target endpoint is geographically located.
    • region: The geographic region where the target endpoint is located. E.g. ‘Oslo’, ‘Dublin’
    • country: The country where the target endpoint or network is geographically located.
    • continent: The continent where the target endpoint resides.
    • latitude: The geographic latitude of the target endpoint.
    • longitude: The geographic longitude of the target endpoint.
    • network: The network associated with the target endpoint - e.g. CloudFlare, Akamai.
    • cdn: The content delivery network associated with the target endpoint - e.g. CloudFlare, Akamai.
    • asn: The Autonomous System Number (ASN) associated with the target endpoint.
  • timing_data: [NOTE: may be null]
    • dns: The number of milliseconds (ms) it took for the DNS lookup.
    • connect: The number of milliseconds (ms) to complete the network connection.
    • tls_handshake: The number of milliseconds (ms) to complete the network connection.
    • upload: The number of milliseconds (ms) the request took to upload to the endpoint server.
    • processing: The number of milliseconds (ms) the endpoint server took to process the request.
    • download: The number of milliseconds (ms) the response download took to complete.
    • total: The number of milliseconds (ms) from the initial request until the response is fully downloaded.
  • location_data: [NOTE: may be null]
    • ip_addr: The IP address where the API call originated, i.e. the location of the APIContext agent.
    • cloud: Name of the cloud provider from where the call originated, i.e. the location of the APIContext agent.
    • city: City from where the call originated, i.e. the location of the APIContext agent.
    • region: The region where the API call originated, i.e. the location of the APIContext agent. E.g. ‘Oslo’, ‘Dublin’
    • country: Country where the API call originated, i.e. the location of the APIContext agent.
    • continent: Continent where the API call originated, i.e. the location of the APIContext agent.
    • latitude: The geographic latitude where the API call originated, i.e. the location of the APIContext agent.
    • longitude: The geographic longitude where the API call originated, i.e. the location of the APIContext agent.
  • dns_records: [NOTE: may be null]
    • a: The DNS A record record for the target endpoint that maps its domain name to its corresponding IPv4 address.
    • ns: The DNS NS record that specifies the name servers responsible for a particular API Call.
    • cname: The DNS C Name record for the target endpoint that maps its domain name to another domain name, effectively aliasing the domain called to another domain.

Updated 10 days ago