Custom Source Responses

What A Source Response Means

A custom source response changes what FastHook sends back to the webhook provider after an incoming request is accepted and queued. It does not change routing, retry, destination signatures, or attempt recording.

The source still has to exist, be enabled, allow the HTTP method, and pass source authentication when auth is configured. Failed method or auth checks are rejected before routing and should stay visible as rejections.

• The response goes back to the provider after accepted ingress.
• A provider 2xx acknowledgement does not prove destination delivery.
• FastHook still creates request records for source-side inspection.
• Accepted requests can create events for every active or paused connection.
• Rejected source auth or method failures do not create delivery attempts.
• Use destination Attempts to prove what a receiver actually returned.

Default Accepted Response

When Customize response is disabled, FastHook uses its default accepted response. This default is useful during debugging because it includes the FastHook request_id that operators can use to find the request record.

• Use the default response when the provider accepts generic JSON.
• Keep request_id visible when the provider can tolerate extra fields.
• Switch to a custom response only when the provider requires a specific body or content type.
• Do not treat the default queued response as destination success.

{
  "ok": true,
  "queued": true,
  "transport": "queue",
  "request_id": "req_..."
}

Configure It In Dashboard

Open the Source settings panel, enable Customize response, choose JSON, TEXT, or XML, enter the exact body, and save. The same panel controls allowed HTTP methods, so keep the method list aligned with the provider contract.

• The dashboard writes config.custom_response when the toggle is enabled.
• Turning Customize response off writes custom_response: null.
• Body is required before saving a custom response.
• JSON bodies must parse as valid JSON before saving.
• Allowed methods default to POST, PUT, PATCH, and DELETE in the dashboard code; enable GET only when the provider actually uses it.

API Shape

Source responses expose the saved config directly through the Sources API. Use PATCH when changing an existing source so unrelated source settings are not replaced accidentally.

The supported custom response content_type values are json, text, and xml. The body is stored as a string because FastHook returns exactly the acknowledgement contract you configure.

• Send custom_response as an object to enable a custom accepted response.
• Send custom_response: null to return to the default queued response.
• Keep allowed_http_methods in the same config when your automation owns the full source settings.
• Use x-team-id with API-key automation when the key can access more than one team.

curl -X PATCH "https://api.fasthook.io/v1/sources/src_xxx" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "custom_response": {
        "content_type": "json",
        "body": "{\"received\":true}"
      },
      "allowed_http_methods": ["POST"]
    }
  }'

curl -X PATCH "https://api.fasthook.io/v1/sources/src_xxx" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "custom_response": null } }'

JSON, Text, And XML Contracts

Pick the smallest response shape that satisfies the provider. JSON is best when the provider validates a machine-readable acknowledgement. Text is useful for simple health-style producers. XML is available for providers or legacy systems that expect XML bodies.

• JSON example: content_type json with body {"received":true}.
• Text example: content_type text with body Accepted.
• XML example: content_type xml with body <ok>true</ok>.
• Do not include API keys, provider secrets, or internal receiver URLs in the body.
• If operators need a correlation handle, include request_id only when your provider accepts it.

{
  "config": {
    "custom_response": {
      "content_type": "text",
      "body": "Accepted"
    }
  }
}

Testing The Response

Test the source URL the same way the provider will call it. Use curl -i so you can see the status line, response headers, and exact response body. Then inspect Requests to confirm FastHook recorded the inbound request.

• Confirm the provider sees the expected body.
• Confirm the content type matches the selected response type.
• Confirm the request appears as accepted in FastHook Requests.
• Confirm connection Events and destination Attempts separately.
• Repeat the test with auth enabled before giving the source URL to a real provider.

curl -i -X POST "https://hook-xxxxxx.fasthook.io/" \
  -H "content-type: application/json" \
  -d '{"type":"provider.test","id":"evt_123"}'

# If the source uses Basic Auth
curl -i -X POST "https://hook-xxxxxx.fasthook.io/" \
  -u provider-user:provider-password \
  -H "content-type: application/json" \
  -d '{"type":"provider.test","id":"evt_123"}'

Rejection Behavior

Custom responses should not hide source boundary failures. If the request uses a disallowed method or fails source authentication, FastHook rejects ingress before queueing and before any destination branch is created.

• SOURCE_METHOD_NOT_ALLOWED means the HTTP method is not in config.allowed_http_methods.
• SOURCE_AUTH_FAILED means the source auth check failed.
• Rejected requests are useful ingress evidence, but they are not delivery events.
• Do not configure a success-looking body to compensate for provider auth or method mistakes.
• Fix the source boundary first, then retest the provider acknowledgement.

What To Inspect Afterward

A provider test can pass as soon as the custom source response matches the provider contract. That is only the first checkpoint. For production confidence, follow the accepted request into route events and destination attempts.

• Requests for source status, rejection_cause, verified, and request_id.
• Events for each connection branch created from the accepted request.
• Attempts for destination status codes, response bodies, retry triggers, and failures.
• Metrics to compare accepted ingress with delivered, failed, held, and queued events.
• The same source_id, connection_id, destination_id, and time window across all views.

When To Use It

• A provider requires a specific acknowledgement body.
• A webhook test screen checks the content type.
• An internal producer expects a simple gateway contract.
• A legacy integration expects text or XML instead of FastHook's default JSON.
• You need to decouple provider acknowledgement from slow destination delivery.

Troubleshooting

• Provider says the response body is wrong: copy the exact saved body from Source settings or the Sources API.
• Provider says JSON is invalid: select JSON and save again so dashboard validation catches parse errors.
• Provider still sees the default body: confirm custom_response is not null and the source you tested is the same provider URL.
• Request is rejected instead of accepted: inspect source auth, allowed_http_methods, and disabled_at.
• Provider test passes but receiver did not process work: inspect Events and Attempts, not the source response.
• No request appears in FastHook: the provider is calling the wrong URL or another environment's source.

Operational Rules

• Keep source response bodies deterministic and small.
• Document which provider contract requires a custom body.
• Avoid secrets and sensitive payload data in source responses.
• Keep custom response settings environment-specific when providers differ between staging and production.
• Prefer the default response during early integration testing because it exposes request_id.
• Use receiver-side idempotency even when the provider acknowledgement succeeds.

Next

• Sources
• Why 200 OK is not enough
• Receive webhooks
• Source authentication