Technical Writing Portfolio

Zendesk sends event-triggered notifications to Slack via outbound webhooks or the official Zendesk for Slack app. The two main delivery paths are:

Failures can occur at any point in this chain. The first step in any investigation is identifying which path is broken.

Classify Before You Investigate

Before touching any configuration, identify which failure class you're dealing with. This avoids chasing the wrong layer.

Zendesk Side

Navigate to Admin Center → Apps and Integrations → Targets (for legacy HTTP targets) or Webhooks (for newer webhook config).

1. Open the relevant webhook or HTTP target.
2. Select Activity or Delivery Log.
3. Filter for failed deliveries in the relevant timeframe.
4. Note the HTTP response code returned by Slack.

Slack Side

In Slack, navigate to your workspace App Management → Custom Integrations → Incoming Webhooks.

1. Confirm the webhook URL still exists and is active.
2. Check which channel it posts to — channels get archived or renamed.
3. If using the Zendesk App rather than a custom webhook, go to Installed Apps → Zendesk and check whether the app shows a configuration error or requires reauthorisation.

Isolate the Integration from Zendesk

Before debugging Zendesk trigger logic, confirm the webhook URL itself is functional by sending a test payload directly.

# Send a test POST to your Slack webhook URL
curl -X POST -H 'Content-type: application/json' \
  --data '{"text": "Webhook test from ops debug - ignore"}' \
  https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# Expected: HTTP 200, message appears in target Slack channel
# If you get 'no_service' or 'invalid_payload': webhook is broken at Slack end
# If you get a 200 but no message: check channel permissions or archival

Common Payload Errors

• Unescaped special characters in ticket subject or body fields breaking JSON structure
• Deprecated attachment fields — Slack has migrated to Block Kit; legacy payload formats may still post but render incorrectly
• Missing required fields — Slack requires at minimum either text or a blocks array
• Channel field included in payload for an Incoming Webhook — Incoming Webhooks post to a fixed channel; adding a channel field causes rejection

Valid Minimal Payload

{
  "text": "[{{ticket.status}}] Ticket #{{ticket.id}}: {{ticket.title}}",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Ticket #{{ticket.id}}*\n{{ticket.title}}"
      }
    }
  ]
}

Token Expiry and Scope Failures

If the Zendesk for Slack app (rather than a raw webhook) is being used, failures are more likely to be OAuth-related.

1. In Zendesk, go to Admin Center → Integrations → Slack. Check whether the integration shows a reconnection prompt — this indicates the OAuth token has expired or been revoked.
2. In Slack, go to Installed Apps → Zendesk → App Settings and confirm the app has the required scopes: chat:write, channels:read, users:read.
3. If scopes have changed (e.g. after a Slack policy update), the app will need to be reauthorised by a Slack admin.

Know What You're Looking For Before You Query

Missing data has three distinct forms. Treating them the same leads to querying the wrong thing.

This guide focuses on the first two. Establish which type you have before writing any query.

Build a Source of Truth First

The most common mistake in missing data investigations is jumping straight to the broken table without first establishing what should be there. Define your expected population from a reliable source, then compare.

-- Step 1: Define expected population
-- All active employees as of the payroll run date
SELECT
  e.employee_id,
  e.full_name,
  e.employment_status,
  e.start_date
FROM employees e
WHERE e.employment_status = 'active'
  AND e.start_date <= '2026-03-01'   -- payroll run date
  AND (e.end_date IS NULL OR e.end_date > '2026-03-01');

-- Step 2: See who actually appeared in the run
SELECT DISTINCT employee_id
FROM payroll_runs
WHERE run_date = '2026-03-01';

-- Step 3: Find the gap
SELECT
  e.employee_id,
  e.full_name,
  e.start_date
FROM employees e
WHERE e.employment_status = 'active'
  AND e.start_date <= '2026-03-01'
  AND (e.end_date IS NULL OR e.end_date > '2026-03-01')
  AND e.employee_id NOT IN (
    SELECT employee_id FROM payroll_runs
    WHERE run_date = '2026-03-01'
  );

Handling NULLs Correctly

-- LEFT JOIN approach: safer when NULLs may be present
SELECT
  e.employee_id,
  e.full_name,
  e.start_date,
  pr.run_date   -- will be NULL if employee is missing from run
FROM employees e
LEFT JOIN payroll_runs pr
  ON e.employee_id = pr.employee_id
  AND pr.run_date = '2026-03-01'
WHERE e.employment_status = 'active'
  AND e.start_date <= '2026-03-01'
  AND (e.end_date IS NULL OR e.end_date > '2026-03-01')
  AND pr.employee_id IS NULL;   -- the gap condition

When the Row Exists But the Data Doesn't

If rows are present but downstream reports are broken, NULL fields are usually the cause. Check systematically.

-- Audit NULLs across key fields for active employees
SELECT
  employee_id,
  full_name,
  CASE WHEN cost_centre IS NULL THEN 'MISSING' ELSE 'OK' END AS cost_centre_status,
  CASE WHEN contract_type IS NULL THEN 'MISSING' ELSE 'OK' END AS contract_type_status,
  CASE WHEN pay_currency IS NULL THEN 'MISSING' ELSE 'OK' END AS currency_status,
  CASE WHEN bank_account_id IS NULL THEN 'MISSING' ELSE 'OK' END AS bank_status
FROM employees
WHERE employment_status = 'active'
  AND (
    cost_centre IS NULL
    OR contract_type IS NULL
    OR pay_currency IS NULL
    OR bank_account_id IS NULL
  );

-- Count scale of the problem
SELECT
  COUNT(*) AS total_active,
  SUM(CASE WHEN cost_centre IS NULL THEN 1 ELSE 0 END) AS missing_cost_centre,
  SUM(CASE WHEN bank_account_id IS NULL THEN 1 ELSE 0 END) AS missing_bank
FROM employees
WHERE employment_status = 'active';

Find Where It Should Have Come From

Once you know which records are missing, trace backwards through the data pipeline to find where the gap was introduced.

-- Check if record exists in staging but not production
SELECT 'staging' AS source, employee_id FROM staging.employees
WHERE employee_id = '12345'
UNION ALL
SELECT 'production' AS source, employee_id FROM employees
WHERE employee_id = '12345';

-- If it's in staging but not production, the ETL step is where it dropped

1. Document the gap: how many records, which fields, which timeframe.
2. Identify the root cause layer (source, sync, transform, permissions).
3. Apply fix at the correct layer — patching production data without fixing the source will recur.
4. Re-run the gap query after the fix to confirm zero results.
5. Add a monitoring query or alert if this data is business-critical.

The Short Version

When your company hires someone in a country where you don't have a legal entity, you can't pay them directly — you're not registered as an employer there. An Employer of Record (EOR) solves this by becoming the legal employer on paper, handling payroll, taxes, and compliance in that country on your behalf.

Your employee still works for you in practice. The EOR handles the legal and administrative layer you can't.

How a Payment Gets From You to Your Employee

The process is more involved than a direct bank transfer. Here is what happens each month, in order:

A common source of confusion is who is responsible for what. The EOR platform automates a lot, but your ops and HR team still owns key inputs.

The goal is to resolve as much as possible at Tier 1 and only escalate when the issue genuinely requires it. Tier 3 should be rare.

Criteria for Tier 1

A ticket stays at Tier 1 if all of the following are true:

• The issue can be resolved using existing documentation, platform access, or standard process
• No changes to employment terms, payroll, or compliance are required
• The employee or requester is not in distress and the issue is not time-critical
• No third-party action (EOR, legal, benefits provider) is required

Tier 1 Examples

Criteria for Escalation to Tier 2

Escalate to Tier 2 when any of the following apply:

• The issue involves a payroll discrepancy or missed payment
• A change to contract terms, salary, or working hours is involved
• The ticket requires cross-system investigation (e.g. HRIS data does not match payroll platform)
• The issue has been open at Tier 1 for more than one business day without resolution
• The employee is asking about tax, legal entitlements, or compliance matters

How to Escalate to Tier 2

1. Add a clear summary note to the ticket: what was reported, what was investigated, what is unresolved.
2. Tag or assign to the relevant specialist using your ticketing system's assignment rules.
3. Do not close or put the ticket on hold — keep it active and update the employee that their issue is being reviewed.
4. If the issue is time-critical (e.g. employee has not been paid), flag as urgent and contact the specialist directly rather than waiting for queue pickup.

Criteria for Escalation to Tier 3

Tier 3 involves escalating outside your team to an EOR provider, benefits vendor, legal counsel, or platform support. This should only happen when:

• The issue requires the EOR to take action on their system (e.g. missed payroll run, incorrect tax filing)
• A platform bug or outage is confirmed or suspected
• Legal advice or a formal employment law determination is needed
• A data protection or compliance incident is involved

External Escalation Process

1. Confirm internally that the issue cannot be resolved without external action.
2. Gather all relevant data before contacting the third party: employee ID, ticket history, dates, error messages, screenshots.
3. Use the designated escalation channel for the provider — do not use general support queues for urgent issues.
4. Log the escalation reference number in the original ticket.
5. Set a follow-up reminder. Do not leave external escalations unmonitored.