This is an archived copy of the APImetrics documentation. For current docs, visit docs.apicontext.com
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

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:
        id: str
        name: str
        description: str
        tags: list[str]
        domain: str
    project_meta:
        id: str
	  	  name: str
        organization: str
        tags: list[str]
    otel_traceparent_id: 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_url: str
    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
    domain_data: 
        age_in_days: int
        dns_provider: str
        fqdn: str
        registrar: str
        tld: str
    tls_certificates: list
				- {
            expiry: str
            issuer: {
                C: str | null = null
                CN: str | null = null
                O: str | null = null
            },
            subject: {
                CN: str | null = 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 8 months ago