A webhook is a custom HTTP callback, which can be triggered by some event from another service, such as:

  • pushing code to a git repository (e.g. GitHub)

  • an app is built and deployed to production (e.g. CircleCI)

  • a new user signed-up to a website (e.g. Auth0)

  • a payment failed (e.g. Stripe )

  • a new order is submitted on an e-commerce app (e.g. Shopify )

  • an app fires a failure event on a logging system (e.g. Datadog )

When one of these events occurs, the source service notifies the webhook API by making a call using an HTTP request. Because webhook APIs are pure HTTP, they can be added to the existing flows without using another layer, such as serverless functions, to call the target API.

Upstash Kafka Webhook API allows to publish these events directly to a user defined topic without using a third-party infrastructure or service.

Signature of the Webhook API is:

[GET | POST] /webhook?topic=$TOPIC_NAME

topic parameter is the target Kafka topic name to store events. Request body is used as the message value and request headers (excluding standard HTTP headers) are converted to message headers.

Webhook API supports both Basic HTTP Authentication and passing credentials as query params when the source service does not support HTTP Auth. When Basic HTTP Auth is not available, user and pass query parameters should be used to send Upstash Kafka REST credentials.

  • Usage with Basic HTTP Auth:

    curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/webhook?topic=my-app-events -u myuser:mypass \
    -d 'some event data'

  • Usage without HTTP Auth:

    curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/webhook?topic=my-app-events&user=myuser&pass=mypass \
    -d 'some event data'

  • With HTTP Headers:

    curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/webhook?topic=my-app-events -u myuser:mypass \
    -d 'some event data' \
    -H "event-timestamp: 1642628041" \
    -H "event-origin: my-app"

    Above webhook call is equivalent to:

    curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/produce -u myuser:mypass \
    -d '{
        "topic": "my-app-events",
        "value": "some event data",
        "headers": [
            {"key": "event-timestamp", "value": "1642628041"},
            {"key": "event-origin", "value": "my-app"},
          ]
        }'