Demo Setup Event Source for Webhook HTTP

This guide shows how to create an Argo Events EventSource that exposes an HTTP webhook, how the webhook maps to CloudEvents-style payloads, and how to verify the EventSource and Service inside your Kubernetes cluster. Use this tutorial to receive webhooks from external systems (GitHub, GitLab, CI/CD tools, custom services) and forward them into Argo’s eventing pipeline. Argo Events supports many sources (AWS SNS, SQS, Azure services, calendar events, GCP Pub/Sub, GitHub, GitLab, Bitbucket, MinIO, Kafka, and more). For this demo we use the webhook EventSource, which runs an HTTP server and transforms incoming requests into CloudEvents-style envelopes.

CloudEvents envelope examples

A typical CloudEvents-style envelope produced by Argo Events contains a context and data section:

{
  "context": {
    "type": "type_of_event_source",
    "specversion": "cloud_events_version",
    "source": "name_of_the_event_source",
    "id": "unique_event_id",
    "time": "event_time",
    "datacontenttype": "type_of_data",
    "subject": "name_of_the_configuration_within_event_source"
  },
  "data": {
    "eventTime": "2025-10-25T10:45:36Z",
    "userPayload": { /* static payload available in the event source */ }
  }
}

When the webhook receives an HTTP request, the event payload typically includes the request headers and body:

{
  "context": {
    "type": "type_of_event_source",
    "specversion": "cloud_events_version",
    "source": "name_of_the_event_source",
    "id": "unique_event_id",
    "time": "event_time",
    "datacontenttype": "type_of_data",
    "subject": "name_of_the_configuration_within_event_source"
  },
  "data": {
    "header": { /* headers from the received HTTP request */ },
    "body": { /* payload received in the HTTP request body */ }
  }
}

Note: the exact structure may vary depending on how the EventSource is configured (e.g., static payloads, custom converters, or secret mappings).

The webhook EventSource listens on the configured port and endpoint. By default, Argo Events will create a Kubernetes Service that exposes the same port. If you want traffic from outside the cluster to reach the webhook, expose the Service using a suitable type for your environment (LoadBalancer, NodePort, Ingress, etc.).

Prerequisites

A Kubernetes cluster with kubectl configured to access it.
Argo Events (controller, eventbus, etc.) installed into a namespace (commonly argo-events).
Optional: an Ingress or LoadBalancer if you need external, public endpoints.

Install Argo Events (if needed)

Apply the upstream manifests to install Argo Events and an example Sensor. Adjust URLs if you use local manifests:

kubectl apply -n argo-events -f https://raw.githubusercontent.com/argoproj/argo-events/master/manifests/install.yaml
kubectl apply -n argo-events -f https://raw.githubusercontent.com/argoproj/argo-events/master/examples/sensor.yaml

Example EventSource manifest (webhook)

Below is an example EventSource that creates:

A webhook listener on port 13000.
An endpoint at /push which accepts only POST requests.
A generated ClusterIP Service exposing port 13000.

apiVersion: argoproj.io/v1alpha1
kind: EventSource
metadata:
  name: webhook
  namespace: argo-events
spec:
  service:
    ports:
      - port: 13000
        targetPort: 13000
  webhook:
    my-webhook:
      port: "13000"
      endpoint: /push
      method: "POST"

Key fields explained:

Field	Purpose	Example
spec.service.ports.port	Port exposed by the generated Kubernetes Service	13000
spec.webhook.<name>.port	Port the webhook server listens on (string)	“13000”
spec.webhook.<name>.endpoint	HTTP path to accept events on	/push
spec.webhook.<name>.method	Restrict allowed HTTP methods (POST, GET, etc.)	”POST”

Apply the manifest (for example save as webhook-eventsource.yaml):

kubectl apply -f webhook-eventsource.yaml

If you created the EventSource via the Argo UI, the same resources are created in the selected namespace.

Verify the EventSource and Service

List resources in the argo-events namespace to confirm the EventSource pod and Service are running:

kubectl get all -n argo-events

Example output (trimmed for clarity):

NAME                                             READY   STATUS    RESTARTS   AGE
pod/controller-manager-59884fd695-kt5gm         1/1     Running   0          16m
pod/eventbus-default-stan-0                     2/2     Running   0          9m
pod/eventbus-default-stan-1                     2/2     Running   0          9m
pod/eventbus-default-stan-2                     2/2     Running   0          9m
pod/webhook-eventsource-8jhxz-b99f96879-nw6pb   1/1     Running   0          24s

NAME                                   TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)           AGE
service/eventbus-default-stan-svc      ClusterIP   None             <none>        4222/TCP,...      9m
service/webhook-eventsource-svc        ClusterIP   10.104.178.99    <none>        13000/TCP         24s

NAME                                        READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/controller-manager          1/1     1            1           16m
deployment.apps/webhook-eventsource-8jhxz   1/1     1            1           24s

NAME                                                   DESIRED   CURRENT   READY   AGE
replicaset.apps/controller-manager-59884fd695          1         1         1       16m
replicaset.apps/webhook-eventsource-8jhxz-b99f96879    1         1         1       24s

NAME                                      READY   AGE
statefulset.apps/eventbus-default-stan    3/3     9m

This confirms:

The webhook EventSource pod is running.
A ClusterIP Service (service/webhook-eventsource-svc) exposes port 13000.

Additional useful commands:

Inspect the EventSource resource:

kubectl -n argo-events get eventsources webhook -o yaml

View cluster events:
kubectl -n argo-events get events

Test the webhook locally (port-forward)

If you don’t have a LoadBalancer or Ingress, port-forward to the Service/pod and test with curl:

Port-forward the Service (or pod) to localhost:

kubectl -n argo-events port-forward svc/webhook-eventsource-svc 13000:13000

In another terminal, POST a test payload:

curl -X POST http://localhost:13000/push \
  -H "Content-Type: application/json" \
  -d '{"message":"hello from curl"}'

Check the EventSource logs to see the incoming request being wrapped into a CloudEvents-style envelope:
kubectl -n argo-events logs -l app=webhook-eventsource

Replace the label selector with the exact Pod/Deployment name if needed.

How the flow works

External systems POST to http://<cluster-ip-or-loadbalancer>:13000/push (or your public ingress URL).
The EventSource receives the request, wraps it into a CloudEvents-like envelope (context + data), and forwards the event onto the configured EventBus.
Sensors in Argo Events consume these events and trigger Argo Workflows, notifications, or other actions.

In the Argo UI (Event Flow or Event Sources view) you should see the new “my-webhook” event source after creation.

Quick troubleshooting

Symptom	Check
No Service on expected port	kubectl -n argo-events get svc - check service/webhook-eventsource-svc ports
POST returns 404	Confirm endpoint path (endpoint: /push) and HTTP method allowed
Events not triggering Sensors	Check EventBus health and Sensor configurations in the same namespace
External webhooks can’t reach cluster	Verify Ingress/LoadBalancer, firewall rules, and DNS routing

If you expose a webhook endpoint to the public internet, secure it: use TLS, require authentication or tokens, validate payloads, and restrict source IPs where possible. An unprotected webhook can be abused or flood your cluster with requests.

Links and references

Use this pattern as a base to extend the webhook EventSource with authentication, custom converters, static payloads, or multiple endpoints per EventSource.

ArgoCD

Argo Workflow

Argo Rollouts

Argo Events

Introduction

Demo Setup Event Source for Webhook HTTP

CloudEvents envelope examples

Prerequisites

Install Argo Events (if needed)

Example EventSource manifest (webhook)

Verify the EventSource and Service

Test the webhook locally (port-forward)

How the flow works

Quick troubleshooting

Links and references

Watch Video

​CloudEvents envelope examples

​Prerequisites

​Install Argo Events (if needed)

​Example EventSource manifest (webhook)

​Verify the EventSource and Service

​Test the webhook locally (port-forward)

​How the flow works

​Quick troubleshooting

​Links and references

Watch Video

CloudEvents envelope examples

Prerequisites

Install Argo Events (if needed)

Example EventSource manifest (webhook)

Verify the EventSource and Service

Test the webhook locally (port-forward)

How the flow works

Quick troubleshooting

Links and references