Skip to Content
FeaturesIntegrationsWebhooks

Webhooks

Webhooks let you build custom integrations for systems that aren’t natively supported. Forget API will call your HTTP endpoint(s) to request a user deletion and, if configured, to check status or cancel. Works for both synchronous and asynchronous providers.

When to use webhooks

  • You need to delete data in an internal system or a third‑party tool that doesn’t have a native Forget API integration yet
  • You want full control over request format, headers, and mapping response statuses to Forget API statuses

Deletion modes

  • Synchronous: your endpoint completes the deletion inline and returns a final result immediately
  • Asynchronous: your endpoint accepts the deletion, returns a tracking ID, and completes later; Forget API periodically checks status

Configuration overview

Each webhook Integration has these sections (see UI):

  1. Deletion Type
  • Choose synchronous or asynchronous
  1. Initiate Deletion (required)
  • Configure endpoint URL, HTTP method, headers, and optional JSON body
  • For async, also provide a JSONPath to extract a tracking ID from the response. This is required so that Forget API can track the progress of the request.
  1. Get Deletion Status (optional, async only)
  • Toggle on to enable polling
  • Configure endpoint, method, headers, optional JSON body
  • Provide a JSONPath to extract a status value from the response and map it to Pending/Success/Failed
  1. Cancel Deletion (optional)
  • Toggle on to enable cancellation
  • Configure endpoint, method, headers, and optional JSON body

Template variables (substitution)

Forget API substitutes variables in endpoint URLs, headers, and JSON bodies before sending requests:

  • System variables

    • {{identifier}}: the user identifier being deleted
    • {{trackingId}}: only for async flows after Initiate Deletion returns one; available in Get Status and Cancel

  • Account (Key‑Value Store) variables

    • If you attach a webhook Account with secrets, each key is available as a template variable
    • Example: if your account has keys apiKey and region, you may use {{apiKey}} and {{region}}

Notes:

  • Bodies are treated as string templates first; if the final value parses as JSON, Forget API sends JSON; otherwise it sends the raw string.
  • GET requests do not include a body.

Initiate Deletion

  • Success (HTTP 2xx–3xx):
    • Synchronous: sub‑request status is set to SUCCESS
    • Asynchronous: Forget API extracts trackingId using your JSONPath, stores it, and moves to PENDING/PROCESSING
  • Failure (HTTP >= 400): sub‑request becomes FAILED with error details

Example request template:

{
  "endpoint": "https://api.example.com/users/{{identifier}}/delete",
  "httpMethod": "POST",
  "headers": [
    { "key": "Authorization", "value": "Bearer {{apiKey}}" },
    { "key": "X-Region", "value": "{{region}}" }
  ],
  "body": "{\n  \"reason\": \"gdpr\",\n  \"requestedBy\": \"forget-api\"\n}"
}

Async tracking ID extraction (JSONPath-like):

  • Supports simple paths like data.trackingId or with a root prefix $.data.trackingId
  • Supports array indexing like data.items[0].id

If extraction fails, the sub‑request is marked FAILED with a helpful error message containing the response and path used.

Get Deletion Status (async)

  • Enable this to let Forget API poll your system until completion.
  • Provide a JSONPath to the status value and a case‑insensitive mapping to internal statuses.

Status mapping example (UI):

{
  "responseJsonPath": "result.status",
  "statusMapping": {
    "pending": ["pending", "processing", "in_progress"],
    "success": ["success", "completed", "done"],
    "failed": ["failed", "error", "canceled"]
  }
}

Mapping behavior:

  • The value at responseJsonPath is compared case‑insensitively against each list
  • Matches produce internal statuses PENDING, SUCCESS, or FAILED
  • If no match, Forget API defaults to PENDING

Cancel Deletion (optional)

  • When enabled, Forget API calls your cancel endpoint (usually using {{trackingId}})
  • On HTTP 2xx–3xx, sub‑request status is set to CANCELED

HTTP semantics and status handling

  • Success is any HTTP status 200–399. Other statuses are treated as failure.
  • GET requests have no body; use path/query params with template variables when needed.
  • When integrating with internal tools, return clear error messages to speed up debugging; they’re surfaced in the sub‑request details.

Security considerations

  • Always use HTTPS endpoints
  • Prefer a webhook Account (key‑value store) to avoid hard‑coding secrets in templates; reference with {{yourKey}}
  • Forget API does not compute HMAC signatures.
Last updated on
IntegrationsDatabases & Warehouses