# Create and verify a Shipfox custom webhook (https://www.shipfox.io/docs/integrations/webhooks/setup)

Description: Create a webhook, inspect a test delivery, and verify that it starts a workflow run.

Use a custom webhook when another system can send HTTP requests. This works
even when Shipfox has no built-in integration for that system. See the [custom
webhook overview](https://www.shipfox.io/docs/integrations/webhooks) for its capabilities.

## Before you begin [#before-you-begin]

You need access to workspace integration settings. You also need a terminal or
system that can send an HTTP `POST` request.

To verify a run, you need a project that can sync workflows and an online runner
with the `shipfox` label.

## Create the integration connection [#create-the-integration-connection]

### Add the webhook

Open **Settings → Integrations**. Select **Custom webhook**, then create an
integration connection with a short slug such as `deploy_hook`.

### Copy the ingest URL

Copy the URL shown after you create the webhook. Keep it secret. Anyone who
has the URL can send events to the integration connection.

### Send a test event

Replace the URL below with the copied value:

```bash
curl -X POST '<your-ingest-url>' \
  -H 'Content-Type: application/json' \
  -d '{"environment":"staging","version":"1.4.2"}'
```

Shipfox should respond with `202 Accepted` and a delivery ID.

## Verify the event [#verify-the-event]

Open **Settings → Events** and filter by the slug of the webhook integration connection. Open the
new `received` event and confirm that its body contains the test values.

## Verify a triggered run [#verify-a-triggered-run]

Create `.shipfox/workflows/check-custom-webhook.yml`. Replace `deploy_hook` with
the integration connection slug. This is a complete workflow:

```yaml
# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Check the custom webhook
runner: shipfox

triggers:
  on_deploy_event:
    source: deploy_hook # Replace with the slug of your webhook integration connection.
    filter: event.body.environment == "staging"

jobs:
  check:
    steps:
      - run: |
          printf 'Staging release: %s\n' "${{ event.body.version }}"
```

Commit and push the workflow to the project's default branch. Wait for **Check
the custom webhook** to sync. Send the same test request again.

Open the new event and its linked run. Confirm that the log prints `Staging
release: 1.4.2`.

The [reference for custom webhook events](https://www.shipfox.io/docs/integrations/webhooks/events) describes
the request and event fields. Read [Events and triggers](https://www.shipfox.io/docs/understand/events-and-triggers)
for the routing model.