How to configure a Filebeat httpjson input

A Filebeat httpjson input pulls events from REST-style APIs into the same pipeline as local logs, which keeps SaaS activity, security findings, and audit feeds searchable without relying on ad hoc polling scripts.

The input issues HTTP requests on a fixed interval, parses JSON responses, and turns the returned data into events. Current httpjson configurations can authenticate with auth.file, standard headers, OAuth2, or AWS signing, and response.split can break an array such as body.events into one event per item before the output stage.

Elastic recommends the CEL input for brand-new custom API integrations that need heavier transforms or multi-step request logic, but httpjson remains supported and is still the shorter path for straightforward JSON polling. When auth.file is used, the token file must normally be locked to 0600 or Filebeat refuses to start, and temporary request tracing can expose headers and response bodies in the logs directory if it is left enabled too long.

1. Create the API token file that httpjson will read for the Authorization header.

   $ printf '%s' 'replace-with-api-token' | sudo tee /etc/filebeat/httpjson-api.token >/dev/null

   A dedicated token file keeps the main YAML readable and avoids repeating the token value in multiple settings. If secrets are already standardized in the Filebeat keystore on the host, a quoted ${KEY} placeholder is also valid. Related: How to create a Filebeat keystore
   Related: How to add a secret to a Filebeat keystore

2. Restrict the token file so only its owner can read or write it.

   $ sudo chmod 600 /etc/filebeat/httpjson-api.token
   $ sudo ls -l /etc/filebeat/httpjson-api.token
   -rw------- 1 root root 22 Apr  2 11:49 /etc/filebeat/httpjson-api.token

   httpjson file auth now checks permissions and can fail startup when the token file is more permissive than 0600.

3. Open the Filebeat configuration file.

   $ sudo nano /etc/filebeat/filebeat.yml

4. Add an httpjson input under filebeat.inputs with the target API URL and the correct split target for the response body.

   filebeat.inputs:
     - type: httpjson
       id: audit-api
       interval: 1m
       auth.file:
         path: /etc/filebeat/httpjson-api.token
         prefix: "Bearer "
       request.url: "https://api.example.net/v1/events"
       response.split:
         target: body.events

   If filebeat.inputs already exists, add another list item under the existing key instead of creating a second filebeat.inputs block.

   Use response.split.target: body.events only when the API response keeps its event list under an events array. If the endpoint returns one JSON object per request, omit response.split. If the response root is the array, use response.split.target: body.

5. Query the API once with the same bearer token to confirm the endpoint returns the expected JSON payload.

   $ curl --silent --show-error --header "Authorization: Bearer $(sudo cat /etc/filebeat/httpjson-api.token)" https://api.example.net/v1/events
   {"events":[{"source":"audit","action":"login","status":"ok"},{"source":"audit","action":"logout","status":"ok"}]}

   Match the scheme, host, path, query string, and any custom headers here to the values that will be used by Filebeat.

6. Test the Filebeat configuration for syntax errors before restarting the service.

   $ sudo filebeat test config -c /etc/filebeat/filebeat.yml
   Config OK

   Related: How to test a Filebeat configuration

7. Restart the Filebeat service to load the new input.

   $ sudo systemctl restart filebeat

   Related: How to manage the Filebeat service with systemctl in Linux

8. Check that the Filebeat service is back in an active state.

   $ sudo systemctl status filebeat --no-pager --lines=12
   ● filebeat.service - Filebeat sends log files to Logstash or Elasticsearch.
        Loaded: loaded (/usr/lib/systemd/system/filebeat.service; enabled; preset: enabled)
        Active: active (running) since Tue 2026-04-02 11:49:06 UTC; 4s ago
      Main PID: 3329 (filebeat)
         Tasks: 12 (limit: 28486)
        Memory: 41.1M (peak: 44.5M)
   ##### snipped #####

   Related: How to manage the Filebeat service with systemctl in Linux

9. Review recent Filebeat logs for the httpjson input and successful requests.

   $ sudo journalctl --unit=filebeat --since "5 min ago" --no-pager | grep -E 'httpjson|request finished|events.json'
   Apr 02 11:49:06 host filebeat[3329]: {"log.level":"info","@timestamp":"2026-04-02T11:49:06.687Z","log.logger":"input.httpjson-stateless","message":"Input 'httpjson-stateless' starting","service.name":"filebeat","id":"audit-api","ecs.version":"1.6.0"}
   Apr 02 11:49:06 host filebeat[3329]: {"log.level":"info","@timestamp":"2026-04-02T11:49:06.687Z","log.logger":"input.httpjson-stateless","message":"Process another repeated request.","service.name":"filebeat","id":"audit-api","input_url":"https://api.example.net/v1/events","ecs.version":"1.6.0"}
   Apr 02 11:49:06 host filebeat[3329]: {"log.level":"info","@timestamp":"2026-04-02T11:49:06.694Z","log.logger":"input.httpjson-stateless","message":"request finished: 2 events published","service.name":"filebeat","id":"audit-api","input_url":"https://api.example.net/v1/events","ecs.version":"1.6.0"}

   Enable request.tracer.enabled only for short troubleshooting windows and write the trace file under /var/log/filebeat/httpjson/. Traced requests can include bearer tokens and full response bodies.