Webhooks

Quickstart: receive and deliver a webhook

Create a source and a destination, connect them, send a webhook, and read how it was delivered.

This quickstart creates a source for payment webhooks, a destination in your app, and a connection between them. Then it sends a webhook to the source and reads how it was delivered.

Before you begin

  • Set up your environment, so HOOKS_API_KEY and HOOKS_URL are set.
  • Have an HTTPS address in your app that answers POST requests with a 2xx status. This quickstart uses https://shop.example.com/webhooks/payments.

Receive and deliver a webhook

  1. Create a source

    curl -X POST "$HOOKS_URL/sources" \
  -H "Authorization: Bearer $HOOKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Payments" }'

    The answer holds the new source. Its url is the address senders send webhooks to. Copy its id and url into variables:

    export SOURCE_ID="the-source-id"
export SOURCE_URL="the-source-url"

  2. Create a destination

    curl -X POST "$HOOKS_URL/destinations" \
  -H "Authorization: Bearer $HOOKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shop",
    "url": "https://shop.example.com/webhooks/payments"
  }'

    Copy the new destination’s id:

    export DESTINATION_ID="the-destination-id"

  3. Connect them

    curl -X POST "$HOOKS_URL/connections" \
  -H "Authorization: Bearer $HOOKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"sourceId\": \"$SOURCE_ID\",
    \"destinationId\": \"$DESTINATION_ID\"
  }"

    From now on, every webhook the source receives is delivered to the destination.

  4. Send a webhook

    Send a webhook to the source, as a payment service would. No API key is needed:

    curl -X POST "$SOURCE_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ORD-104233",
    "amount": 25000,
    "msisdn": "255745123456",
    "status": "COMPLETED"
  }'

    The source answers 200 with {"status":"received"}. The webhook is kept from this moment.

  5. Read the delivery

    List the destination’s deliveries. The newest is first:

    curl "$HOOKS_URL/deliveries?destination=$DESTINATION_ID" \
  -H "Authorization: Bearer $HOOKS_API_KEY"

    When your app answered with a 2xx status, the delivery’s status is delivered. If it is retrying or failed, lastErrorClass and lastError say why. See View events and deliveries.

Clean up

Delete the source if you do not want it to keep receiving webhooks. This deletes its connections and its events too, and cannot be undone:

curl -X DELETE "$HOOKS_URL/sources/$SOURCE_ID" \
  -H "Authorization: Bearer $HOOKS_API_KEY"

What’s next

Last updated